diff --git a/Documentation/AdvancedBuildInstructions.md b/Documentation/AdvancedBuildInstructions.md index 5301163e194..6dba89a382f 100644 --- a/Documentation/AdvancedBuildInstructions.md +++ b/Documentation/AdvancedBuildInstructions.md @@ -79,3 +79,13 @@ Outside of QEMU, Serenity will run on VirtualBox and VMware. If you're curious, ## Running SerenityOS on bare metal Bare curious users may even consider sourcing suitable hardware to [install Serenity on a physical PC.](BareMetalInstallation.md) + +## Filesystem performance on Windows + +If you're using the native Windows QEMU binary, QEMU is not able to access the ext4 root partition +of the WSL2 installation without going via the 9P network file share. The root of your WSL2 distro will begin at the +network path `\\wsl$\{distro-name}`. + +Alternatively, you may prefer to copy `Build/_disk_image` and `Build/Kernel/Kernel` to a native Windows partition (e.g. +`/mnt/c`) before running `ninja run`, in which case `SERENITY_DISK_IMAGE` will be a regular Windows path (e.g. +`'D:\serenity\_disk_image'`). diff --git a/Documentation/BuildInstructionsWindows.md b/Documentation/BuildInstructionsWindows.md index 9d7fc218740..3134fab1b61 100644 --- a/Documentation/BuildInstructionsWindows.md +++ b/Documentation/BuildInstructionsWindows.md @@ -11,6 +11,18 @@ Once installed, you will need to make sure the distribution you want to use (and - `wsl --set-version ` is used to convert a distro to another version, and
- `wsl --set-default-version 2` will set the default version for all new distros (if desired.)
+## Note on filesystems + +WSL2 filesystem performance for IO heavy tasks (such as compiling a large C++ project) on the host Windows filesystem is +pretty bad. See [this issue on the WSL GitHub project](https://github.com/microsoft/WSL/issues/4197#issuecomment-604592340) +for details. + +The recommendation from the Microsoft team on that issue is: + +> If it's at all possible, store your projects in the Linux file system in WSL2. + +In practice, this means cloning and building the project to somewhere such as `/home/username/serenity`. + ## Setting up build tools Please see the general build instructions for a list of tools you need to install in your WSL Linux environment. As a @@ -19,57 +31,35 @@ section to set up QEMU on your host system. ## Setting up QEMU -- Grab the latest QEMU binaries from [here](https://www.qemu.org/download/#windows) and install them. At a minimum you +Grab the latest QEMU binaries from [here](https://www.qemu.org/download/#windows) and install them. At a minimum you will need to install the tools as well as the system emulators for i386 and x86_64. ![QEMU Components](QEMU_Components.png) -- Locate the executable `qemu-system-x86_64.exe` in WSL. -By default this will be located at `/mnt/c/Program Files/qemu/qemu-system-x86_64.exe`. +Locate the `qemu-system-x86_64.exe` executable in WSL. +By default this will be at `/mnt/c/Program Files/qemu/qemu-system-x86_64.exe`. -- Set the `SERENITY_QEMU_BIN` environment variable to the location above. For example: \ +Set the `SERENITY_QEMU_BIN` environment variable to that location. For example: \ `export SERENITY_QEMU_BIN='/mnt/c/Program Files/qemu/qemu-system-x86_64.exe'` -- `ninja run` as usual. +Run `Meta/serenity.sh run` to build and run SerenityOS as usual. ### Hardware acceleration -The steps above will run QEMU in software virtualisation mode, which is very slow. +The steps above will run QEMU in software virtualization mode, which is very slow. QEMU supports hardware acceleration on Windows via the [Windows Hypervisor Platform](https://docs.microsoft.com/en-us/virtualization/api/) -(WHPX), a user-mode virtualisation API that can be used alongside Hyper-V. +(WHPX). -To run SerenityOS in a WHPX-enabled QEMU VM: - -- If you have not already done so, enable Windows Hypervisor Platform, either using "Turn Windows features on or off", - or by running the following command in an elevated PowerShell session: \ +Enable the Windows Hypervisor Platform feature, either using "Turn Windows features on or off", or by running the +following command in an elevated PowerShell session: \ `dism /Online /Enable-Feature /All /FeatureName:HypervisorPlatform` ![WHPX Windows Feature](WHPX_Feature.png) -- Specify QEMU acceleration option: \ +Set the `SERENITY_VIRT_TECH_ARG` environment variable in your WSL2 shell: \ `export SERENITY_VIRT_TECH_ARG="-accel whpx,kernel-irqchip=off"` -- Start the VM with `Meta/serenity.sh run` as usual. +You might want to add those environment variables to your shell's configuration file, so that you don't have to set them +manually each time you start a new shell. -## Note on filesystems - -WSL2 filesystem performance for IO heavy tasks (such as compiling a large C++ project) on the host Windows filesystem is -terrible. This is because WSL2 runs as a Hyper-V virtual machine and uses the 9P file system protocol to access host -Windows files, over Hyper-V sockets. - -For a more in depth explanation of the technical limitations of their approach, see -[this issue on the WSL GitHub project](https://github.com/microsoft/WSL/issues/4197#issuecomment-604592340) - -The recommendation from the Microsoft team on that issue is: - -> If it's at all possible, store your projects in the Linux file system in WSL2. - -In practice, this means cloning and building the project to somewhere such as `/home/username/serenity`. - -If you're using the native Windows QEMU binary from the above steps, QEMU is not able to access the ext4 root partition -of the WSL2 installation without going via the 9P network file share. The root of your WSL2 distro will begin at the -network path `\\wsl$\{distro-name}`. - -Alternatively, you may prefer to copy `Build/_disk_image` and `Build/Kernel/Kernel` to a native Windows partition (e.g. -`/mnt/c`) before running `ninja run`, in which case `SERENITY_DISK_IMAGE` will be a regular Windows path (e.g. -`'D:\serenity\_disk_image'`). +Start the VM with `Meta/serenity.sh run` as usual.