beenull/ladybird
1
0
Fork 0
mirror of https://github.com/LadybirdBrowser/ladybird.git synced 2024-11-26 09:30:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7
ladybird/Documentation/NotesOnWSL.md

104 lines
6.1 KiB
Markdown
Raw Normal View History

Meta: Move "Notes on WSL" to a separate file in Documentation/ Since this is not relevant to the majority of people, let's move it out of the way.
2019-11-06 20:03:18 +00:00
## Notes on WSL
Meta: Update CLion and WSL configuration documentations This commit updates CLionConfiguration.md and NotesOnWSL.md so that they comply with new build system. In addition to that, the WSL doc is updated to include instructions to run qemu (and serenity) natively on Windows, without needing an X-window server.
2020-05-17 13:56:46 +00:00
SerenityOS can also be built and run under WSL Version 2.
WSL Version 1 is not supported since Version 1 does not support ext2, which is needed for the setup.
Meta: Move "Notes on WSL" to a separate file in Documentation/ Since this is not relevant to the majority of people, let's move it out of the way.
2019-11-06 20:03:18 +00:00
Documentation: Add filesystem note to WSL2 notes WSL2 is now available in non-insider builds of Windows, starting with version 2004. Add a filesystem note regarding use of /mnt/c et al from WSL2 for compiling serenity. Namely, recommend against it as the performance across the 9p file system protocol is terrible for IO heavy jobs.
2020-06-27 17:51:32 +00:00
WSL Version 2 requires Windows version 2004 or higher, with OS Build 19041 or greater. Here is a guide on how to [get WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
Meta: Update CLion and WSL configuration documentations This commit updates CLionConfiguration.md and NotesOnWSL.md so that they comply with new build system. In addition to that, the WSL doc is updated to include instructions to run qemu (and serenity) natively on Windows, without needing an X-window server.
2020-05-17 13:56:46 +00:00
Once installed, you will need to make sure the distribution you want to use (and the new default) is using Version 2:
Documentation: added additional info about moving to wsl2
2020-04-08 20:15:55 +00:00
- `wsl -l -v` will list distros and versions,<br/>
Meta: Update CLion and WSL configuration documentations This commit updates CLionConfiguration.md and NotesOnWSL.md so that they comply with new build system. In addition to that, the WSL doc is updated to include instructions to run qemu (and serenity) natively on Windows, without needing an X-window server.
2020-05-17 13:56:46 +00:00
- `wsl --set-version <distro> <version>` is used to convert a distro to another version, and<br/>
Documentation: added additional info about moving to wsl2
2020-04-08 20:15:55 +00:00
- `wsl --set-default-version 2` will set the default version for all new distros (if desired.)<br/>
The installation then proceeds as usual.
Meta: Move "Notes on WSL" to a separate file in Documentation/ Since this is not relevant to the majority of people, let's move it out of the way.
2019-11-06 20:03:18 +00:00
Meta: Update CLion and WSL configuration documentations This commit updates CLionConfiguration.md and NotesOnWSL.md so that they comply with new build system. In addition to that, the WSL doc is updated to include instructions to run qemu (and serenity) natively on Windows, without needing an X-window server.
2020-05-17 13:56:46 +00:00
WSL2 does not natively support graphical applications.
Docs: clarify steps to use Windows-native QEMU when building under WSL This now descibes how to get the regular `make run` workflow to work under Windows using native QEMU. It describes how to override the QEMU binary path, as well as overriding the SerenityOS disk image file location with a native Windows path. Also fixes some minor spelling and punctuation issues.
2020-08-14 11:49:55 +00:00
You can either install QEMU natively on windows and allow WSL to talk to it, or you can install an X Server for windows.
Meta: Update CLion and WSL configuration documentations This commit updates CLionConfiguration.md and NotesOnWSL.md so that they comply with new build system. In addition to that, the WSL doc is updated to include instructions to run qemu (and serenity) natively on Windows, without needing an X-window server.
2020-05-17 13:56:46 +00:00
### Setting up an X server with WSL:
- Install [Vcxsrv](https://sourceforge.net/projects/vcxsrv/) on Windows.
- When you start up Vcxsrv, make sure to set the Display number to 0, and to Disable access control.
- Before actually doing **make run**, you need to set the DISPLAY environmental variable as such:
Meta: Move "Notes on WSL" to a separate file in Documentation/ Since this is not relevant to the majority of people, let's move it out of the way.
2019-11-06 20:03:18 +00:00
```bash
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
```
This is due to a bug in WSL2. For more information, microsoft/WSL#4106.
Meta: Update CLion and WSL configuration documentations This commit updates CLionConfiguration.md and NotesOnWSL.md so that they comply with new build system. In addition to that, the WSL doc is updated to include instructions to run qemu (and serenity) natively on Windows, without needing an X-window server.
2020-05-17 13:56:46 +00:00
- Connect to the window server from WSL.
Now you can finally, **make run**.
Docs: clarify steps to use Windows-native QEMU when building under WSL This now descibes how to get the regular `make run` workflow to work under Windows using native QEMU. It describes how to override the QEMU binary path, as well as overriding the SerenityOS disk image file location with a native Windows path. Also fixes some minor spelling and punctuation issues.
2020-08-14 11:49:55 +00:00
### Using native QEMU install with WSL:
- Grab latest QEMU from [here](https://www.qemu.org/download/#windows) and install for Windows.
Meta: Update CLion and WSL configuration documentations This commit updates CLionConfiguration.md and NotesOnWSL.md so that they comply with new build system. In addition to that, the WSL doc is updated to include instructions to run qemu (and serenity) natively on Windows, without needing an X-window server.
2020-05-17 13:56:46 +00:00
- Locate the executable `qemu-system-i386.exe` in WSL.
Docs: clarify steps to use Windows-native QEMU when building under WSL This now descibes how to get the regular `make run` workflow to work under Windows using native QEMU. It describes how to override the QEMU binary path, as well as overriding the SerenityOS disk image file location with a native Windows path. Also fixes some minor spelling and punctuation issues.
2020-08-14 11:49:55 +00:00
By default this will be located at `/mnt/c/Program Files/qemu/qemu-system-i386.exe`.
- Set the `SERENITY_QEMU_BIN` environment variable to the location above. For example: \
`export SERENITY_QEMU_BIN='/mnt/c/Program Files/qemu/qemu-system-i386.exe'`
Meta: Update CLion and WSL configuration documentations This commit updates CLionConfiguration.md and NotesOnWSL.md so that they comply with new build system. In addition to that, the WSL doc is updated to include instructions to run qemu (and serenity) natively on Windows, without needing an X-window server.
2020-05-17 13:56:46 +00:00
Docs: clarify steps to use Windows-native QEMU when building under WSL This now descibes how to get the regular `make run` workflow to work under Windows using native QEMU. It describes how to override the QEMU binary path, as well as overriding the SerenityOS disk image file location with a native Windows path. Also fixes some minor spelling and punctuation issues.
2020-08-14 11:49:55 +00:00
- Locate the _Windows_ path to the SerenityOS disk image, as native QEMU will be accessing it via the Windows filesystem. If your build tree is located in the WSL2 partition, this will be accessible under the `\\wsl$` network file share (see [notes below](#note-on-filesystems)).
Meta: Move "Notes on WSL" to a separate file in Documentation/ Since this is not relevant to the majority of people, let's move it out of the way.
2019-11-06 20:03:18 +00:00
Docs: clarify steps to use Windows-native QEMU when building under WSL This now descibes how to get the regular `make run` workflow to work under Windows using native QEMU. It describes how to override the QEMU binary path, as well as overriding the SerenityOS disk image file location with a native Windows path. Also fixes some minor spelling and punctuation issues.
2020-08-14 11:49:55 +00:00
- Set the `SERENITY_DISK_IMAGE` environment variable to the full path of the SerenityOS disk image file from above. For example: \
`export SERENITY_DISK_IMAGE='\\wsl$\Ubuntu-20.04\home\username\serenity\Build\_disk_image'`
- `make run` as usual.
Documentation: Add filesystem note to WSL2 notes WSL2 is now available in non-insider builds of Windows, starting with version 2004. Add a filesystem note regarding use of /mnt/c et al from WSL2 for compiling serenity. Namely, recommend against it as the performance across the 9p file system protocol is terrible for IO heavy jobs.
2020-06-27 17:51:32 +00:00
Docs: explain how to enable QEMU hardware acceleration on Windows Describes how to enable QEMU hardware acceleration on Windows using the Windows Hypervisor Platform feature.
2020-08-14 12:19:30 +00:00
#### Hardware acceleration
The steps above will run QEMU in software virtualisation 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.
This is important to note as WSL2 itself runs on top of Hyper-V, which conflicts with other acceleration technologies such as Intel HAXM.
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: \
`dism /Online /Enable-Feature /All /FeatureName:HypervisorPlatform`
- Specify QEMU acceleration option: \
`export SERENITY_EXTRA_QEMU_ARGS="-accel whpx"`
- Disable Virtual Machine eXtensions on the vCPU, otherwise some versions of QEMU will crash out with a "WHPX: Unexpected VP exit code 4" error: \
`export SERENITY_QEMU_CPU="max,vmx=off"`
- `make run` as usual.
Docs: Update WSL notes with some workarounds for known issues
2020-12-30 18:07:35 +00:00
#### Known issues with WHPX
##### Freeze on boot in Scheduler
If Serenity freezes on boot with the log message: `Scheduler[0]: idle loop running` then you are likely missing some emulated CPU features.
Please ensure you have installed the most recent version of [QEMU for Windows](https://qemu.weilnetz.de/) and that you have followed the step above to enable the maximum feature set available:
`export SERENITY_QEMU_CPU="max,vmx=off"`.
##### Illegal instruction on boot
Using `SERENITY_QEMU_CPU="max"` can trigger a QEMU bug where the OSXSAVE CPUID flag is erroneously set, playing havoc with feature detection logic in libgcc and resulting in this error.
To workaround this, first adjust the `SERENITY_QEMU_CPU` setting to emulate a more restricted feature set. `SERENITY_QEMU_CPU="qemu32"` appears to work in some cases, however in others causes the boot freeze issue above.
It's worth playing around with various different values here to see if you can find one that works for you. Running `qemu-system-i386.exe -cpu ?` will list the supported CPU configurations.
If you cannot find a working CPU feature set, the next workaround is to patch libgcc in the Serenity toolchain build to remove the offending instruction.
Comment out the `if ((ecx & bit_OSXSAVE))` block in `Toolchain/Tarballs/gcc-<version>/libgcc/config/i386/cpuinfo.c`. In GCC 10.2.0 this is lines 282-297.
Rebuild the toolchain using `Toolchain/BuildIt.sh` as normal, then rebuild Serenity.
Documentation: Add filesystem note to WSL2 notes WSL2 is now available in non-insider builds of Windows, starting with version 2004. Add a filesystem note regarding use of /mnt/c et al from WSL2 for compiling serenity. Namely, recommend against it as the performance across the 9p file system protocol is terrible for IO heavy jobs.
2020-06-27 17:51:32 +00:00
### Note on filesystems
WSL2 filesystem performance for IO heavy tasks (such as compiling a large C++ project) on the host Windows filesystem is terrible.
Docs: clarify steps to use Windows-native QEMU when building under WSL This now descibes how to get the regular `make run` workflow to work under Windows using native QEMU. It describes how to override the QEMU binary path, as well as overriding the SerenityOS disk image file location with a native Windows path. Also fixes some minor spelling and punctuation issues.
2020-08-14 11:49:55 +00:00
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.
Documentation: Add filesystem note to WSL2 notes WSL2 is now available in non-insider builds of Windows, starting with version 2004. Add a filesystem note regarding use of /mnt/c et al from WSL2 for compiling serenity. Namely, recommend against it as the performance across the 9p file system protocol is terrible for IO heavy jobs.
2020-06-27 17:51:32 +00:00
Everywhere: Fix more typos
2020-10-02 21:14:37 +00:00
For a more in depth explanation of the technical limitations of their approach, see [this issue on the WSL github](https://github.com/microsoft/WSL/issues/4197#issuecomment-604592340)
Documentation: Add filesystem note to WSL2 notes WSL2 is now available in non-insider builds of Windows, starting with version 2004. Add a filesystem note regarding use of /mnt/c et al from WSL2 for compiling serenity. Namely, recommend against it as the performance across the 9p file system protocol is terrible for IO heavy jobs.
2020-06-27 17:51:32 +00:00
The recommendation from the Microsoft team on that issue is:
Meta: Fix typo in NotesOnWSL.md (#3086)
2020-08-11 12:27:00 +00:00
> If it's at all possible, store your projects in the Linux file system in WSL2.
Documentation: Add filesystem note to WSL2 notes WSL2 is now available in non-insider builds of Windows, starting with version 2004. Add a filesystem note regarding use of /mnt/c et al from WSL2 for compiling serenity. Namely, recommend against it as the performance across the 9p file system protocol is terrible for IO heavy jobs.
2020-06-27 17:51:32 +00:00
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
Docs: clarify steps to use Windows-native QEMU when building under WSL This now descibes how to get the regular `make run` workflow to work under Windows using native QEMU. It describes how to override the QEMU binary path, as well as overriding the SerenityOS disk image file location with a native Windows path. Also fixes some minor spelling and punctuation issues.
2020-08-14 11:49:55 +00:00
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 `make run`, in which case `SERENITY_DISK_IMAGE` will be a regular Windows path (e.g. `'D:\serenity\_disk_image'`)
Reference in a new issue Copy permalink