Merge branch 'patch-1' into 'main'

Draft: Document what I did on Asahi Linux

See merge request lvra/lvra.gitlab.io!115

content/docs/distros/Asahi_Linux.md

@@ -0,0 +1,127 @@
+---
+title: Asahi Linux
+---
+
+# Asahi Linux
+
+*AKA: Fedora on aarch64 with extra steps*
+
+## Envision
+
+Fedora has the `envision` package, as well as the `envision-monado` and `envision-wivrn` metapackages which grab the necessary dependencies for building monado and wivrn, respectively.
+This *will not* be the most up-to-date with upstream envision, but seeing as Envision doesn't currently build aarch64 AppImages, this is the easiest way to build custom commits of monado/wivrn/opencomposite/xrizer for arm64, specifically.
+If you are looking to use non-native VR applications, or [Steam Games](#steam-games-under-muvm), you should continue on into the [Multiarch](#multiarch) section.
+
+## Multiarch
+
+Depending on what openxr applications you are planning on running, you may need multiple builds of the same component, but for different architectures.
+You can acquire these builds in multiple ways, such as cross-compiling, or gathering builds from multiple machines.
+
+A repo ([vr-multiarch-build]) for cross-compiling these components has been thrown together to make things easier.
+You will need podman, as well as the typical runtime dependencies.
+Some sample usage:
+
+```sh
+git clone https://gitlab.com/lvra/vr-multiarch-build
+cd vr-multiarch-build
+# `./setup_wivrn.sh` and `./setup_xrizer.sh` also exist, depending on what you need.
+./setup_monado.sh && ./setup_opencomposite.sh
+sudo ./setcap.sh
+
+# you can now start monado by running prefixes/monado-aarch64/bin/monado-service
+```
+
+When you want to update a component, you should manually pull the git repos, then rerun the setup scripts. For example:
+
+```sh
+cd vr-multiarch-build
+git pull # update the build repository
+git -C monado pull
+git -C OpenComposite pull
+./setup_monado.sh && ./setup_opencomposite.sh
+sudo ./setcap.sh
+```
+
+## Steam Games under muvm
+
+What worked for me was running `monado-service` manually, with all the environment variables that envision uses, and manually setting up environment variables for steam launch arguments.
+On my machine, the steam launch arguments look like: `XR_RUNTIME_JSON=~/.config/openxr/1/active_runtime.x86_64.json PRESSURE_VESSEL_FILESYSTEMS_RW=/run/user/1000/wivrn/comp_ipc:/run/user/1000/monado_comp_ipc %command%`
+
+There are some extra complications caused by interactions between muvm and pressure-vessel, you may wish to put the following inside of a script somewhere for now:
+```sh
+#!/usr/bin/env bash
+
+# I couldn't find a way to make PRESSURE_VESSEL_FILESYSTEMS_RW map one file/directory to another,
+# so let's create pressure-vessel's view of XDG_RUNTIME_DIR instead.
+# This won't be necessary once pressure-vessel supports passing through openxr runtimes.
+mkdir -p /run/user/1000/wivrn/
+chmod 700 /run/user/1000/
+ln -s $XDG_RUNTIME_DIR/monado_comp_ipc /run/user/1000/
+ln -s $XDG_RUNTIME_DIR/wivrn/comp_ipc /run/user/1000/wivrn/
+
+# wivrn: Work around https://github.com/AsahiLinux/muvm/issues/178
+ping -c1 8.8.8.8
+
+# setup the environment variables for monado or wivrn
+
+# launch monado or wivrn
+# path/to/vr-multiarch-build/prefixes/monado-aarch64/bin/monado-service
+# dbus-launch path/to/vr-multiarch-build/prefixes/wivrn-aarch64/bin/wivrn-server --no-publish-service --no-manage-active-runtime
+```
+
+For ease, going forward, I will assume that this script is located within the home directory, named `launch_monado.sh`, and has the executable bit set.
+Therefore, my reccomended launch order is as follows:
+
+1. Lanuch monado:
+```sh
+muvm -it -- ~/launch_monado.sh
+```
+
+2. Launch Steam.
+  - Due to a [bug](https://pagure.io/fedora-asahi/steam/issue/18) in the steam launcher wrapper on asahi, the "Launching Steam" window will not stick around, but Steam *is* still launching.
+  - If you get a message from OpenComposite complaining that it doesn't support VR Applications of type 6, then you should attempt to re-launch steam, as that will cause Steam to fail to launch.
+
+3. Optionally, `tail -f ~/.steam/steam/logs/console-linux.txt` so you can tell what's going on if a game fails to find the openvr/openxr runtimes.
+
+4. Ensure that `openvrpaths.vrpath` has the correct contents.
+
+5. Launch a game.
+
+### wivrn
+
+Due to <https://github.com/AsahiLinux/muvm/issues/177>, the terminal that you're running WiVRn within *must* be the one that's starting the VM.
+Therefore, you should start wivrn before you start steam.
+
+The avahi daemon is not available inside of muvm, so you should use `--no-publish-service`.
+Since I'm managing my active runtimes through [vr-multiarch-build], I'm using `--no-manage-active-runtime`.
+
+If you are using a commit of WiVRn before <https://github.com/WiVRn/WiVRn/commit/38b64fe09c27757109f126d91b9a5f4244e01f78>, the build system *will* produce inconsistent commit hashes for its build of monado across architectures.
+
+To work around this, you can:
+- `git cherry-pick 38b64fe09c27757109f126d91b9a5f4244e01f78` onto your wivrn branch
+- use a newer commit of wivrn that includes that commit
+- add `IPC_IGNORE_VERSION=1` to your steam launch arguments
+
+If you pick the last option, you need to be *extra careful* that you are actually building things off of the same commit of wivrn/monado.
+
+Assuming a similar script to the one described above, named `launch_wivrn.sh`, my reccomended launch order is as follows:
+
+1. Launch wivrn:
+```sh
+muvm -it -p 9757/udp -p 9757 -- ~/launch_wivrn.sh
+```
+2. Connect your headset.
+3. Start steam.
+4. etc.
+
+## Troubleshooting
+
+### VkPhysicalDevice does not support required extension VK_KHR_external_semaphore
+
+VK_KHR_external_semaphore support was re-enabled in `Mesa 25.1.0-asahi20250425`.
+Ensure that your mesa version is up-to-date, and is a revision that comes after this one.
+
+Aside: It sounds like the asahi fork of mesa will not be necessary, soon.
+However, switching to mainline [breaks virglrenderer](<https://github.com/chadmed/asahi-overlay/commit/34e50cc47c6a75ccd421b27f6ad5ded1dee4f402>) as of the time of writing.
+
+[vr-multiarch-build]: https://gitlab.com/lvra/vr-multiarch-build