Add updated WSL2 Instructions

[hecksadecimal]

Objective

• Clarify usage of bevy within WSL2 and provide temporary solution to developing Bevy projects within it

Solution

• Suggest cross-compiling for Windows and configuring to run the build target for Windows, sidestepping the compatibility problem outright while still permitting people to use WSL2 as a development platform.

[alice-i-cecile]

These are much more helpful directions. Thank you!

Note: this came from helping in #5013.

[IceSentry]

If I'm not mistaken, I believe these instructions are only relevant to wsl2 on windows 10. On windows 11 it should be able to use wslg which is better supported for graphics through wsl.

In other words, this section should probably link to https://github.com/microsoft/wslg to mention it's a possible option that doesn't need cross compiling.

[hecksadecimal]

If I'm not mistaken, I believe these instructions are only relevant to wsl2 on windows 10. On windows 11 it should be able to use wslg which is better supported for graphics through wsl.

In other words, this section should probably link to https://github.com/microsoft/wslg to mention it's a possible option that doesn't need cross compiling.

Unfortunately no, WSLg has the exact same limitation as described, you cannot use vulkan with it yet, and bevy can't use opengl.

microsoft/wslg#40

[IceSentry]

Ah, right, I haven't used wsl in a while so I didn't really follow up that space. I stopped using it around when wslg was announced.

[hecksadecimal]

Wish there was a way to go about this without cross compilation but I just don't see it happening until bevy supports opengl. WSL2 supporting vulkan seems pretty far off, assuming it will ever support it in the first place.

[Hellzbellz123]

you can use xwin to compile to windows msvc using xwin from within wsl, (not cargo-xwin, they do similar stuff but not this one) this doesnt require mingw to exist on windows to run, and can be statically linked so users dont need any other libraries
steps
you can change paths so you dont want sudo but i was fine with it

1. cargo install xwin
2. rustup target add x86_64-pc-windows-msvc
3. run sudo ~/.cargo/bin/xwin --accept-license splat --output /opt/xwin
4. add snippet below to cargo.toml
5. cargo build --target=x86_64-pc-windows-msvc

[target.x86_64-pc-windows-msvc]
linker = "lld-link"
rustflags = [
 # "-C", "target-feature=+crt-static",
  "-Zshare-generics=off",
  "-Lnative=/opt/xwin/crt/lib/x86_64",
  "-Lnative=/opt/xwin/sdk/lib/um/x86_64",
  "-Lnative=/opt/xwin/sdk/lib/ucrt/x86_64",
]

[kwilson33]

I've just started playing around with Bevy today, and got it setup with WSL2 (Ubuntu) on Windows 10. My laptop has
AMD Ryzen 7 PRO 4750U Mobile Processor with AMD Radeon™ Graphics.

I could be misunderstanding something, but I wanted to say that I got the breakout example mentioned in the Bevy Getting Started guide working without running any X server. I'm a total Rust and Bevy beginner, so I could be missing something.😊But... it seems to work! No X server needed. The command I ran to launch the breakout example, copied from the guide, was:
cargo run --example breakout.
And my DISPLAY variable is set to :0.

I believe this means the existing WSLg version works with Bevy? I don't see anywhere where this is documented, so I thought it was worth pointing out. However, I could be missing the point that @hecksadecimal brought up:

Unfortunately no, WSLg has the exact same limitation as described, you cannot use vulkan with it yet, and bevy can't use opengl.

Before I get into all the details, the trick that got it working for me that wasn't documented was installing the libvulkan1 package alongside mesa-vulkan-drivers.

I'll document my steps/setup here.

I first started by following the steps on Installing Linux dependencies and installing the below packages. Not sure if I needed to install the Wayland packages. I guess I could test that.

sudo apt-get install g++ pkg-config libx11-dev libasound2-dev libudev-dev
# If using Wayland, you will also need to install
sudo apt-get install libwayland-dev libxkbcommon-dev

At this point, I did NOT install mesa-vulkan-drivers even though they are mentioned in the guide. Why? Because I first tried vulkan-radeon and vulkan-intel and they didn't work, and I guess I forgot to try mesa-vulkan-drivers.

Then I followed the steps linked in the guide WSL documentation to set up graphics and audio.
I downloaded VcXsrv , and followed the steps.

At this point, running cargo run --example breakout still didn't work. so I just started Googling a bunch of stuff.
I eventually landed on this page Install And Test Vulkan On Linux.

I followed the steps under Vulkan on Ubuntu Linux, with a slight change.

# Add the PPA to your system and update. I doubt this is necessary to get things working, but I was just following the guide.
sudo add-apt-repository ppa:oibaf/graphics-drivers
sudo apt update
sudo apt upgrade

sudo apt install libvulkan1 mesa-vulkan-drivers vulkan-utils

# The vulkan-utils package couldn't be found, so I ran the below command instead
sudo apt install libvulkan1 mesa-vulkan-drivers 

Then, I ran cargo run --example breakout again and it worked!
I exited out of VcXsrv to figure out if it was making things work. Once closed, the command still worked.

My DISPLAY variable was set to :0.

I also removed the libvulkan1 package and tried running again. It did not work without the libvulkan1 package.
So it seems like WSL2 + WSLg will work with Bevy, with the correct packages installed.

Summary

Without any X server running like VcXsrv, I am able to run a graphical Bevy application on WSL2 (Ubuntu) on Windows 10 using an AMD graphics card (integrated graphics).

This leads me to believe that WSLg works pretty well with Bevy. Maybe it doesn't work with everything? I am not certain about OpenGL and Vulkan, but I wasn't able to find anyone else mentioning this.

Maybe this can be worked into the guide? Specifically the part about needing to install the libvulkan1 package in addition to mesa-vulkan-drivers. Of course, this depends on your setup.

I'm interested to hear what others say and I hope this was helpful!

[benny-n]

I managed to get Vulkan working with WSL2 on Windows 11, but I had to clone mesa, build it from source with the experimental Microsoft Dzn driver for Vulkan over D3D12, and then run my bevy app with:

WGPU_BACKEND=vulkan VK_ICD_FILENAMES=/usr/local/share/vulkan/icd.d/dzn_icd.x86_64.json cargo run

Full flow:

sudo apt-get install build-essential git
sudo apt-get build-dep mesa
# If the second command yields `E: You must put some 'deb-src' URIs in your sources.list`,
# edit your "/etc/apt/sources.list" and remove '#' manually (or with your favorite editing tool) from deb-src URIs.
# Then, save the file and run `sudo apt update && sudo apt upgrade`.
# NOTE: you should probably save a backup of "/etc/apt/sources.list" before overriding it
git clone https://gitlab.freedesktop.org/mesa/mesa.git
cd mesa
# The next command will build Mesa from source in "./mesa/build" with the experimental Dzn driver 
# and install it in "/usr/local/share/vulkan/icd.d". To install to a local folder, 
# try running with `--prefix=$HOME/wsl-dev` (full disclosure, I haven't tried this option)
meson setup ./build -Dvulkan-drivers=microsoft-experimental && cd build && sudo ninja install

# Now, with everything in place, we can run our bevy app with Vulkan on WSL2!
export WGPU_BACKEND=vulkan
export VK_ICD_FILENAMES=/usr/local/share/vulkan/icd.d/dzn_icd.x86_64.json
cargo run

# Or simply
WGPU_BACKEND=vulkan VK_ICD_FILENAMES=/usr/local/share/vulkan/icd.d/dzn_icd.x86_64.json cargo run

[stephenmartindale]

I was experimenting with this, today, and I can confirm that the notes contributed by @kwilson33 are accurate …

… and it is possible to get Bevy's examples (well, breakout, at the least) to run under the WSL on Windows 10 and one can actually do it without any PPAs – with everything installed by apt or official sources.

In brief, starting from a fresh Ubuntu 22.10 environment under the WSL, this almost suffices:

sudo apt-get install g++ pkg-config libx11-dev libasound2-dev libudev-dev \
                     libwayland-dev libxkbcommon-dev \
                     libvulkan1 mesa-vulkan-drivers

But it does not. Some prerequisite is missing.

I know where to go, next, however: Microsoft suggest one might run gedit under the WSL and, on a whim, I tried that to see if my issues were with Bevy – I had guessed Vulkan-related – or with graphical apps in general …

sudo apt install gedit -y
gedit ~/.bashrc

… and gedit was quite happy to run.

AND after gedit and its dependencies had been installed by apt, so would Bevy's examples!

So, great. It works. Everything from apt, no PPAs. Nothing compiled from source excepting Bevy, of course.

(It also works after a wsl.exe --shutdown and a new WSL session so it is not the case that executing gedit was starting up some service related to X or Vulkan or WSLg. I'm fairly certain that gedit's relevance was the provision of some package or other.)

Next Steps

My next line of investigation will be to try out the approach proposed last week by @benny-n and to look deeper into precisely what is coming in with gedit and try to make a minimal apt-get install … set.

Some Versions

Here are some version numbers and diagnostic outputs from my experiment, today:

Bevy was at revision d623731e.

wsl.exe --version:

WSL version: 1.2.0.0
Kernel version: 5.15.90.1
WSLg version: 1.0.51
MSRDC version: 1.2.3770
Direct3D version: 1.608.2-61064218
DXCore version: 10.0.25131.1002-220531-1700.rs-onecore-base2-hyp
Windows version: 10.0.19045.2846

lsb_release -d: Ubuntu 22.10

cat /mnt/wslg/versions.txt:

WSLg ( x86_64 ): 1.0.51+Branch.main.Sha.435b42ad093d8c9e785b57f2455098db2e3508c0
Mariner: VERSION="2.0.20230107"
DirectX-Headers:
mesa:
pulseaudio: 2f0f0b8c3872780f15e275fc12899f4564f01bd5
FreeRDP: c574044a10003e50453acb4cf42801c5833fb572
weston: f09791f3314de7b414bf21a46940ff684d936eaf

[benny-n]

I think it's also important to note that from my observations Vulkan uses llvmpipe as the default driver when rendering in WSL2, therefore even though it works out of the box without any PPA as shown in the comment above, it renders from the CPU's integrated graphics instead of using the actual graphics card, or at least for me it did. @stephenmartindale, can you confirm this?

I tried making it render through the GPU by playing with env variables and config files, but eventually the only thing that worked was cloning mesa from source like I explained in this comment

[stephenmartindale]

Yeah. I can confirm what @benny-n says: my experiment was using llvmpipe at runtime, too.

Current Opinions

Having done some further experiments, my current opinion is that my original cross-compilation approach that used xwin and a script to post files over to the host's NTFS file-system for execution was best. I've had that operational for some time, now, but the script is not pretty.

Ignoring the actual execution from the host file-system, advantages of cross-compilation with xwin are:

1. There is less setup because one does not need to wrangle ALSA or rely on WSLg (which implies not just WSL 2 but a modern release of the WSL 2) or install a bunch of dependencies from apt at all.
2. The run-time experience is as close to native as makes no difference.
3. Cross-compiled artefacts are deployable to Windows native users.
4. The work is relevant for cross-compilation from any Linux environment – not just the WSL.
5. The work is distro. agnostic: xwin can be sourced via cargo (or even just curl, from its releases page) and may even be deleted after xwin splat has fetched the required headers and libraries.

Verdict on this Documentation Change

Personally, I would judge that the best thing to do with the Bevy documentation – as it stands – is to extirpate all mention of W.S.L. 2 from linux_dependencies.md.

The section certainly does not belong there as a sub-section of the Ubuntu instructions because it pertains to Windows – not Ubuntu – and, even on Windows, should theoretically be distro.-agnostic in the most ideal case.

Instead, perhaps a document specifically presenting a brief summary of possible approaches (xwin and MSVC, mingw, libvulkan1, Microsoft's experimental DZN driver...) is more appropriate. This document could be linked in from linux_dependencies.md and other place, as appropriate, and would exist only to make the reader aware of what is possible and where to direct their research.

That document could provide comprehensive instructions for any approaches that "just work" and do not incur undesirable compromises like the use of CPU rendering (And I would argue that, today, there aren't any that truly fit this mandate.) or link out to other sources of long-form material or perhaps GitHub gists that provide more detailed walkthroughs – presumably including discussions of their compromises.

At some point, I will get around to cleaning up my own scripts and approach and I've even a Dockerfile that recreates my entire dev. environment (to be imported into the WSL) but I hardly think that all of that belongs in the Bevy docs folder, although I would be happy to contribute it, should anyone claim otherwise.

How about it? I have time and have done a fair bit of reading and experimentation on the subject so I could write up a "summary of approaches"-style thing, to supersede this MR, if that would be welcomed.

[stephenmartindale]

I have opened #8383 with a draft summary-of-approaches document, based on discussions, here.

It's a first-draft (I haven't even done a grammar pass on it) but please feel free to give me some feedback. Specifically, I'd like to know:

• Does this "summary of approaches" approach make sense?
• Have I missed anything obvious?
• Have I overly emphasised or discredited an approach or lead the reader to believe that one approach is "blessed"?
• Should I split out my discussion of cross-compilation into another file?
• Where does the unofficial cheat-book stand in all of this? Should I integrate its contents? Now? Or in the future? Should I even link it?

Also, to me, it seems obvious why such a document SHOULD exist (There's clearly interest in using the WSL 2 as one's dev. environment.) but do I need to spell that out in the merge request, anyway, as some kind of motivation section?

[alice-i-cecile]

do I need to spell that out in #8383, anyway, as some kind of motivation section?

This should be fine: it's fairly self-evident and this thread is linked for those who really need to know more.

[maciekglowka]

Hi all,

inspired by this thread I am experimenting a bit with WSLg as well.

It seems for me that apart form the dependencies mentioned by @stephenmartindale

sudo apt-get install g++ pkg-config libx11-dev libasound2-dev libudev-dev \
                     libwayland-dev libxkbcommon-dev \
                     libvulkan1 mesa-vulkan-drivers

only one extra was needed to run:

libxcursor1

Although I am not on a clean install. (didn't use the WSLg here before though at all).

The sound is not working for me yet. But it also was not working when I tried the gedit route on a different WSL instance.

Probably I should soon try this on a clean install again to confirm any missing libraries

[bas-ie]

Closing as part of backlog cleanup: while it seems the comments here generated some useful tips that should still show up on Bevy repo searches, the original PR is no longer likely to be accurate/relevant.