beenull/ladybird
1
0
Fork 0
mirror of https://github.com/LadybirdBrowser/ladybird.git synced 2024-11-25 00:50:22 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

Documentation: Condense the Windows build instructions some more

Browse source
This commit is contained in:
Gunnar Beutner 2021-07-12 11:09:17 +02:00 committed by Andreas Kling
parent 0da89376b7
commit 4db286e63f
Notes: sideshowbarker 2024-07-18 09:11:33 +09:00 
Author: https://github.com/gunnarbeutner
Commit: https://github.com/SerenityOS/serenity/commit/4db286e63fb
Pull-request: https://github.com/SerenityOS/serenity/pull/8678
2 changed files with 35 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
Documentation/AdvancedBuildInstructions.md
View file

@ -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'`).

60
Documentation/BuildInstructionsWindows.md
View file

@ -11,6 +11,18 @@ Once installed, you will need to make sure the distribution you want to use (and
- `wsl --set-version <distro> <version>` is used to convert a distro to another version, and<br/>
- `wsl --set-default-version 2` will set the default version for all new distros (if desired.)<br/>
## 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.