|
|
@@ -0,0 +1,290 @@ |
|
|
# Full desktop shell in WSL2 using WSLg (XWayland) |
|
|
|
|
|
> [!NOTE] |
|
|
> If you want to use Wayland in WSLg in a simpler setup, you can try the [WSLg (Wayland) tutorial](../7def60bccc8ae32cf9cacb41064b1c0f). |
|
|
|
|
|
In this tutorial, we will setup GUI in WSL2. No additional software outside WSL (like VcXsrv or GWSL) is required. You will find this tutorial very similar to the one that [replaces Xorg with Xvnc](../385636cbae39fc8cd0937139e87b1c74). Indeed, it's pretty much the same tutorial, with some few changes. |
|
|
|
|
|
The key component we need to install is the desktop metapackage you want (GNOME, KDE, Xfce, Budgie, etc), and after that, replace the default Xorg by a script that calls Xwayland instead. |
|
|
|
|
|
For this setup, I will use Ubuntu 24.04, and install GNOME Desktop. Unfortunately older versions of Ubuntu lack some fundamental things, so we cannot reproduce it in older versions (at least not fully). Since the key components aren't bound to Ubuntu or GNOME, you can use your favorite distro and GUI. Check the [Sample screenshots](#sample-screenshots) section for examples. |
|
|
|
|
|
So let's go. First, we need a working [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) installation. |
|
|
|
|
|
> [!WARNING] |
|
|
> WSLg may not work as expected, since Wayland sockets are disabled for everyone, and not every app can handle this. But if you want to use Wayland apps natively, you can use the command `export XDG_RUNTIME_DIR=$HOME/runtime-dir` and then start your WSLg app. |
|
|
|
|
|
Before going to real business, let's make sure we are updated. |
|
|
|
|
|
``` |
|
|
sudo apt update |
|
|
sudo apt upgrade |
|
|
``` |
|
|
|
|
|
You also need to make sure `/etc/wsl.conf` have the following lines: |
|
|
|
|
|
``` |
|
|
[boot] |
|
|
systemd=true |
|
|
``` |
|
|
|
|
|
If not, create/edit this file, add these lines and restart WSL (for example, using `wsl.exe --shutdown`, then reopening the distro terminal). |
|
|
|
|
|
Now we are ready to go. |
|
|
|
|
|
## Installing components |
|
|
|
|
|
### Installing GUI |
|
|
|
|
|
1. First you select your favorite desktop environment metapackage. Here is a list of the most common metapackages: |
|
|
|
|
|
<table> |
|
|
<thead> |
|
|
<tr><th>Distro</th><th>Desktop Environment</th><th>Metapackage</th></tr> |
|
|
</thead> |
|
|
<tbody> |
|
|
<tr><td rowspan="9">Ubuntu</td><td>Budgie</td><td><code>ubuntu-budgie-desktop</code> (currently very buggy, I don't recommend using it)</td></tr> |
|
|
<tr><td>GNOME</td><td><code>ubuntu-desktop</code></td></tr> |
|
|
<tr><td>KDE</td><td><code>kubuntu-desktop</code></td></tr> |
|
|
<tr><td>Kylin</td><td><code>ubuntukylin-desktop</code></td></tr> |
|
|
<tr><td>LXDE</td><td><code>lubuntu-desktop</code></td></tr> |
|
|
<tr><td>MATE</td><td><code>ubuntu-mate-desktop</code></td></tr> |
|
|
<tr><td>Studio</td><td><code>ubuntustudio-desktop</code></td></tr> |
|
|
<tr><td>Unity</td><td><code>ubuntu-unity-desktop</code></td></tr> |
|
|
<tr><td>Xfce</td><td><code>xubuntu-desktop</code></td></tr> |
|
|
<tr><td rowspan="8">Ubuntu/Debian</td><td>Cinnamon</td><td><code>task-cinnamon-desktop</code></td></tr> |
|
|
<tr><td>GNOME</td><td><code>task-gnome-desktop</code></td></tr> |
|
|
<tr><td>GNOME Flashback</td><td><code>task-gnome-flashback-desktop</code></td></tr> |
|
|
<tr><td>KDE Plasma</td><td><code>task-kde-desktop</code></td></tr> |
|
|
<tr><td>LXDE</td><td><code>task-lxde-desktop</code></td></tr> |
|
|
<tr><td>LXQt</td><td><code>task-lxqt-desktop</code></td></tr> |
|
|
<tr><td>MATE</td><td><code>task-mate-desktop</code></td></tr> |
|
|
<tr><td>Xfce</td><td><code>task-xfce-desktop</code></td></tr> |
|
|
</tbody> |
|
|
</table> |
|
|
|
|
|
1. Once you have chosen the metapackage, let's install it. For example, if you choose `ubuntu-desktop`, the command will be: |
|
|
|
|
|
``` |
|
|
sudo apt install ubuntu-desktop xwayland |
|
|
``` |
|
|
|
|
|
This will install the `ubuntu-desktop` and `xwayland` (if not already included as dependency for your metapackage). The installation will take a while, so be patient. |
|
|
|
|
|
1. If in Ubuntu, you may want to install `snap-store`. If you don't need it, you can skip this step: |
|
|
|
|
|
``` |
|
|
sudo snap install snap-store |
|
|
``` |
|
|
|
|
|
## Configuring the environment |
|
|
|
|
|
If you are using Debian, you need to configure the locale (this is not needed in Ubuntu): |
|
|
|
|
|
``` |
|
|
echo "LANG=en_US.UTF-8" | sudo tee -a /etc/default/locale |
|
|
``` |
|
|
|
|
|
### Create and modify services |
|
|
|
|
|
1. Now we have everything installed, we need to fix the directory `/tmp/.X11-unix/`, because it's mounted as read-only by default. We will create a new systemd unit: |
|
|
|
|
|
``` |
|
|
sudo systemctl edit --full --force wslg-fix.service |
|
|
``` |
|
|
|
|
|
1. Paste the code below in the editor: |
|
|
|
|
|
``` |
|
|
[Service] |
|
|
Type=oneshot |
|
|
ExecStart=-/usr/bin/umount /tmp/.X11-unix |
|
|
ExecStart=/usr/bin/rm -rf /tmp/.X11-unix |
|
|
ExecStart=/usr/bin/mkdir /tmp/.X11-unix |
|
|
ExecStart=/usr/bin/chmod 1777 /tmp/.X11-unix |
|
|
ExecStart=/usr/bin/ln -s /mnt/wslg/.X11-unix/X0 /tmp/.X11-unix/X0 |
|
|
ExecStart=/usr/bin/chmod 0777 /mnt/wslg/runtime-dir |
|
|
ExecStart=/usr/bin/chmod 0666 /mnt/wslg/runtime-dir/wayland-0.lock |
|
|
|
|
|
[Install] |
|
|
WantedBy=multi-user.target |
|
|
``` |
|
|
|
|
|
1. Exit the editor saving the changes to the file. |
|
|
|
|
|
1. Let's enable `wslg-fix.service`: |
|
|
|
|
|
``` |
|
|
sudo systemctl enable wslg-fix.service |
|
|
``` |
|
|
|
|
|
1. We also need to remove all references to Wayland, because if not, some apps (`gnome-terminal`, for example) will open outside the desktop shell. We will edit the `[email protected]` service: |
|
|
|
|
|
``` |
|
|
sudo systemctl edit [email protected] |
|
|
``` |
|
|
|
|
|
1. Paste the code below in the editor: |
|
|
|
|
|
``` |
|
|
[Service] |
|
|
ExecStartPost=-/usr/bin/rm -f /run/user/%i/wayland-0 /run/user/%i/wayland-0.lock |
|
|
``` |
|
|
|
|
|
1. Now we will change the default startup target, because if not, a shell window will appear everytime you start your distro (for example, opening a Terminal of your distro in Windows). |
|
|
|
|
|
``` |
|
|
sudo systemctl set-default multi-user.target |
|
|
``` |
|
|
|
|
|
1. Restart WSL using `wsl.exe --shutdown`, then reopen your distro terminal. |
|
|
|
|
|
### Replacing default Xorg by XWayland |
|
|
|
|
|
By default, the display manager call multiple `Xorg` instances, one for each user session, including the login screen, provided by GDM (if you are using the GDM as your display manager, of course). So we will replace `Xorg` script by a new version which calls `Xwayland` instead the classic `Xorg`. This is the real magic we are trying to do. |
|
|
|
|
|
1. First, let's backup the original `Xorg` script. |
|
|
|
|
|
``` |
|
|
sudo mv /usr/bin/Xorg /usr/bin/Xorg.original |
|
|
``` |
|
|
|
|
|
1. Then, we create a new `Xorg` script. |
|
|
|
|
|
``` |
|
|
sudo nano /usr/bin/Xorg.Xwayland |
|
|
``` |
|
|
|
|
|
1. Paste the code below in the editor: |
|
|
|
|
|
``` |
|
|
#!/bin/bash |
|
|
for arg do |
|
|
shift |
|
|
case $arg in |
|
|
# Xwayland doesn't support vtxx argument. So we convert to ttyxx instead |
|
|
vt*) |
|
|
set -- "$@" "${arg//vt/tty}" |
|
|
;; |
|
|
# -keeptty is not supported at all by Xwayland |
|
|
-keeptty) |
|
|
;; |
|
|
# -novtswitch is not supported at all by Xwayland |
|
|
-novtswitch) |
|
|
;; |
|
|
# other arguments are kept intact |
|
|
*) |
|
|
set -- "$@" "$arg" |
|
|
;; |
|
|
esac |
|
|
done |
|
|
|
|
|
# Check if the runtime dir is present, and create it if not |
|
|
if [ ! -d $HOME/runtime-dir ] |
|
|
then |
|
|
mkdir $HOME/runtime-dir |
|
|
ln -s /mnt/wslg/runtime-dir/wayland-0 /mnt/wslg/runtime-dir/wayland-0.lock $HOME/runtime-dir/ |
|
|
fi |
|
|
|
|
|
# Point the XDG_RUNTIME_DIR variable to $HOME/runtime-dir |
|
|
export XDG_RUNTIME_DIR=$HOME/runtime-dir |
|
|
|
|
|
# Find an available display number |
|
|
for displayNumber in $(seq 1 100) |
|
|
do |
|
|
[ ! -e /tmp/.X11-unix/X$displayNumber ] && break |
|
|
done |
|
|
|
|
|
# Here you can change or add options to fit your needs |
|
|
command=("/usr/bin/Xwayland" ":${displayNumber}" "-geometry" "1920x1080" "-fullscreen" "$@") |
|
|
|
|
|
systemd-cat -t /usr/bin/Xorg echo "Starting Xwayland:" "${command[@]}" |
|
|
|
|
|
exec "${command[@]}" |
|
|
``` |
|
|
|
|
|
Please note the resolution of the virtual screen. You can change that to fit your needs (1366x768, 3840x2160, etc). |
|
|
|
|
|
1. Finally, we set the correct permissions for the file and create a link to it: |
|
|
|
|
|
``` |
|
|
sudo chmod 0755 /usr/bin/Xorg.Xwayland |
|
|
sudo ln -sf Xorg.Xwayland /usr/bin/Xorg |
|
|
``` |
|
|
|
|
|
> [!WARNING] |
|
|
> Sometimes, system updates replace `Xorg` link with the original version. Just repeat this step if this happens, and `Xwayland` will work again as `Xorg` replacement. |
|
|
|
|
|
## Running your distro with GUI enabled |
|
|
|
|
|
Now you have everything ready to start. Just do the following command: |
|
|
|
|
|
``` |
|
|
sudo systemctl start graphical.target |
|
|
``` |
|
|
|
|
|
After a while (usually a few seconds, but it can take more if you don't have a SSD), the login screen must appear. |
|
|
|
|
|
After logging in, the logged user's desktop must appear. When you log out, the screen will show the login interface again. This applies to GDM (which is the case if you installed Ubuntu Desktop). In GDM, you can change this behavior changing the configuration file like this: |
|
|
|
|
|
1. `sudo nano /etc/gdm3/custom.conf` |
|
|
|
|
|
1. Uncomment and edit the following lines: |
|
|
|
|
|
``` |
|
|
AutomaticLoginEnable=true |
|
|
AutomaticLogin=[your username without the brackets] |
|
|
``` |
|
|
|
|
|
## Shutting down |
|
|
|
|
|
One important thing is: once you start your WSL instance, you cannot just stop it. You must perform a standard Linux shutdown. You can do one of the alternatives below: |
|
|
|
|
|
- Power off option on GUI menu |
|
|
- `sudo poweroff` |
|
|
|
|
|
After doing that, you can safely shut down your WSL instance, either by `wsl.exe --terminate` or `wsl.exe --shutdown`. Not doing the shutdown process may cause damage to your WSL instance. So be careful. |
|
|
|
|
|
## Troubleshooting |
|
|
|
|
|
1. If it doesn't work at first, try to check your `journalctl` logs: |
|
|
|
|
|
``` |
|
|
journalctl -b -t /usr/lib/gdm3/gdm-x-session -t /usr/bin/Xorg --no-pager |
|
|
``` |
|
|
|
|
|
If you are using Debian, then the command is: |
|
|
``` |
|
|
journalctl -b -t /usr/libexec/gdm-x-session -t /usr/bin/Xorg --no-pager |
|
|
``` |
|
|
|
|
|
In the output, you must see what command line was generated for `Xwayland`, and which error messages appear. Of course, even if it works correctly, you can check the logs just to see what is happening, or for debugging. |
|
|
|
|
|
1. You must check if the custom `Xorg` script was not replaced by the default version of it. If it was the case, just repeat the steps of [Replacing default Xorg by Xwayland](#replacing-default-xorg-by-xwayland) section. |
|
|
|
|
|
1. Check if `Xorg` is your default display server, not `Xephyr` or `Wayland`. If it's not, you must change it to have `Xorg` as your default display server. |
|
|
|
|
|
1. If you are using LightDM, you also need to check logs at `/var/log/lightdm` (you will need to use sudo to cat files in that directory). The `Xwayland` output will be in the file `/var/log/lightdm/x-0.log`. |
|
|
|
|
|
1. If it still doesn't work, you can try to restart WSL with `wsl.exe --shutdown` (don't forget to save everything that is unsaved before, because WSL will shut down completely), then open your distro terminal again and repeat the steps of section [Running your distro with GUI enabled](#running-your-distro-with-gui-enabled). |
|
|
|
|
|
## Sample screenshots |
|
|
|
|
|
### GDM |
|
|
|
|
|
 |
|
|
|
|
|
### LightDM (Kubuntu) |
|
|
 |
|
|
|
|
|
### GNOME |
|
|
 |
|
|
|
|
|
### KDE (Kubuntu) |
|
|
 |
|
|
|
|
|
### LXDE (Lubuntu) |
|
|
 |
|
|
|
|
|
### Xfce (Xubuntu) |
|
|
 |
tdcosta100 revised this gist