diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 61 |
1 files changed, 19 insertions, 42 deletions
@@ -9,18 +9,23 @@ A minimal root filesystem for running NixOS on WSL. It can be used with [DistroLauncher](https://github.com/microsoft/WSL-DistroLauncher) as `install.tar.gz` or as input to `wsl --import --version 2`. +## System requirements + +NixOS-WSL is tested with the Windows Store version of WSL 2, which is now available on all supported Windows releases (both 10 and 11). +Support for older "inbox" versions is best-effort. + ## Quick start -First, [download the latest release\'s installer](https://github.com/nix-community/NixOS-WSL/releases/latest). +First, [download the latest release](https://github.com/nix-community/NixOS-WSL/releases/latest). Then open up a Terminal, PowerShell or Command Prompt and run: ```sh -wsl --import NixOS .\NixOS\ nixos-wsl-installer.tar.gz --version 2 +wsl --import NixOS .\NixOS\ nixos-wsl.tar.gz --version 2 ``` This sets up a new WSL distribution `NixOS` that is installed under -`.\NixOS`. `nixos-wsl-installer.tar.gz` is the path to the file you +`.\NixOS`. `nixos-wsl.tar.gz` is the path to the file you downloaded earlier. You might need to change this path or change to the download directory first. You can now run NixOS: @@ -29,11 +34,6 @@ You can now run NixOS: wsl -d NixOS ``` -The installer will unpack the file system and subsequently start NixOS. -A few warnings about file systems and locales will pop up. You can -safely ignore them. After systemd has started, you should be greeted -with a bash prompt inside your fresh NixOS installation. - If you want to make NixOS your default distribution, you can do so with ```sh @@ -68,57 +68,34 @@ If you have a flakes-enabled Nix, you can use the following command to build your own tarball instead of relying on a prebuilt one: ```cmd -nix build github:nix-community/NixOS-WSL#nixosConfigurations.mysystem.config.system.build.installer +sudo nix run github:nix-community/NixOS-WSL#nixosConfigurations.modern.config.system.build.tarballBuilder ``` Or, if you want to build with local changes, run inside your checkout: ```cmd -nix build .#nixosConfigurations.mysystem.config.system.build.installer +sudo nix run .#nixosConfigurations.your-hostname.config.system.build.tarballBuilder ``` Without a flakes-enabled Nix, you can build a tarball using: ```cmd -nix-build -A nixosConfigurations.mysystem.config.system.build.installer -``` +nix-build -A nixosConfigurations.mysystem.config.system.build.tarballBuilder && sudo ./result/bin/nixos-wsl-tarball-builder -The resulting installer tarball can then be found under -`./result/tarball/nixos-wsl-installer.tar.gz`. +``` -You can also build a rootfs tarball without wrapping it in the installer -by replacing `installer` with `tarball` in the above commands. The -rootfs tarball can then be found under -`./result/tarball/nixos-wsl-x86_64-linux.tar.gz`. +The resulting tarball can then be found under `nixos-wsl.tar.gz`. ## Design Getting NixOS to run under WSL requires some workarounds: -### systemd support - -WSL comes with its own (non-substitutable) init system while NixOS uses -systemd. Simply starting systemd later on does not work out of the box, -because systemd as system instance refuses to start if it is not PID 1. -This unfortunate combination is resolved in two ways: - -- the user\'s default shell is replaced by a wrapper script that acts - is init system and then drops to the actual shell -- systemd is started in its own PID namespace; therefore, it is PID 1. - The shell wrapper (see above) enters the systemd namespace before - dropping to the shell. - -### Installer - -Usually WSL distributions ship as a tarball of their root file system. -These tarballs however, can not contain any hard-links due to the way -they are unpacked by WSL, resulting in an \"Unspecified Error\". By -default some Nix-derivations will contain hard-links when they are -built. This results in system tarballs that can not be imported into -WSL. To circumvent this problem, the rootfs tarball is wrapped in that -of a minimal distribution (the installer), that is packaged without any -hard-links. When the installer system is started for the first time, it -overwrites itself with the contents of the rootfs tarball. +- instead of directly loading systemd, we use a small shim that runs the NixOS activation scripts first +- some additional binaries required by WSL's internal tooling are symlinked to FHS paths on activation + +Running on older WSL versions also requires a workaround to spawn systemd by hijacking the root shell and +spawning a container with systemd inside. This method of running things is deprecated and not recommended, +however still available as `nixos-wsl-legacy.tar.gz` or via `wsl.nativeSystemd = false`. ## License |