jcs.org
Serenity Operating System
1# Setting up a development environment on Windows
2
3SerenityOS can be built and run under WSL Version 2.
4WSL Version 1 is not supported since Version 1 does not support ext2, which is needed for the setup.
5
6WSL Version 2 requires Windows 10 version 2004 or higher, with OS Build 19041 or greater. Here is a guide on how to
7[get WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
8
9Once installed, you will need to make sure the distribution you want to use (and the new default) is using Version 2:
10- `wsl -l -v` lists distros and versions,<br/>
11- `wsl --set-version <distro> <version>` is used to convert a distro to another version, and<br/>
12- `wsl --set-default-version 2` will set the default version for all new distros (if desired.)<br/>
13
14Next, go to [BuildInstructions.md](https://github.com/SerenityOS/serenity/blob/master/Documentation/BuildInstructions.md#prerequisites)
15and follow the instructions for your chosen Linux environment, to get the needed build tools.
16
17## Note on filesystems
18
19WSL2 filesystem performance for IO heavy tasks (such as compiling a large C++ project) on the host Windows filesystem is
20pretty bad. See [this issue on the WSL GitHub project](https://github.com/microsoft/WSL/issues/4197#issuecomment-604592340)
21for details.
22
23The recommendation from the Microsoft team on that issue is:
24
25> If it's at all possible, store your projects in the Linux file system in WSL2.
26
27In practice, this means cloning and building the project to somewhere such as `/home/username/serenity`. You can then
28access the linux filesystem at `\\wsl$`, so for example, the project would be at `\\wsl$\home\username\serenity`.
29
30## Setting up QEMU
31
32Grab the latest QEMU binaries from [here](https://www.qemu.org/download/#windows) and install them. At a minimum you
33will need to install the tools, the system emulators for i386 and x86_64, and
34the DLL libraries.
35
36
37
38Run `Meta/serenity.sh run` to build and run SerenityOS as usual.
39
40### Hardware acceleration
41
42The steps above will run QEMU in software virtualization mode, which is very slow.
43QEMU supports hardware acceleration on Windows via the [Windows Hypervisor Platform](https://docs.microsoft.com/en-us/virtualization/api/)
44(WHPX).
45
46Enable the Windows Hypervisor Platform feature, either using "Turn Windows features on or off", or by running the
47following command in an elevated PowerShell session: \
48`dism /Online /Enable-Feature /All /FeatureName:HypervisorPlatform`
49
50
51
52You may have to reboot after enabling the WHPX feature.
53
54Afterwards you can start the VM with `Meta/serenity.sh run` as usual.