From 3271df78f951cd41265b96f91d3079d8238f0804 Mon Sep 17 00:00:00 2001 From: mtkennerly Date: Sat, 12 Oct 2024 16:14:47 -0400 Subject: [PATCH] #390: Add troubleshooting info for GUI not appearing --- README.md | 24 ++++-------------------- docs/help/troubleshooting.md | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+), 20 deletions(-) create mode 100644 docs/help/troubleshooting.md diff --git a/README.md b/README.md index 9a12f7c..b978dc9 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,7 @@ Note: + Detailed help documentation is available for several topics. @@ -99,6 +100,9 @@ Detailed help documentation is available for several topics. * [Environment variables](/docs/help/environment-variables.md) * [Logging](/docs/help/logging.md) +### Other +* [Troubleshooting](/docs/help/troubleshooting.md) + ## Community The community has created some additional resources you may find useful. @@ -142,25 +146,5 @@ cross-platform and cross-store solution: * Database is not actively updated. As of 2022-11-16, the last update was 2018-06-05. * No command line interface. -## Troubleshooting -* The window content is way too big and goes off screen. - * Try setting the `WINIT_X11_SCALE_FACTOR` environment variable to `1`. - Flatpak installs will have this set automatically. -* The file/folder picker doesn't work. - * **Linux:** Make sure that you have Zenity or kdialog installed and available on the `PATH`. - The `DISPLAY` environment variable must also be set. - * **Steam Deck:** Use desktop mode instead of game mode. - * **Flatpak:** The `DISPLAY` environment variable may not be getting passed through to the container. - This has been observed on GNOME systems. - Try running `flatpak run --nosocket=fallback-x11 --socket=x11 com.github.mtkennerly.ludusavi`. -* On Windows 11, when I open the GUI, a console window also stays open. - * This is a limitation of the new Windows Terminal app (https://github.com/microsoft/terminal/issues/14416). - It should be fixed once Windows Terminal v1.17 is released. - In the meantime, you can work around it by opening Windows Terminal from the Start Menu, - opening its settings, and changing the "default terminal application" to "Windows Console Host". -* The GUI won't launch. - * There may be an issue with your graphics drivers/support. - Try using the software renderer instead by setting the `ICED_BACKEND` environment variable to `tiny-skia`. - ## Development Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md). diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md new file mode 100644 index 0000000..a65ca65 --- /dev/null +++ b/docs/help/troubleshooting.md @@ -0,0 +1,36 @@ +# Troubleshooting +* The window content is way too big and goes off screen. + * Try setting the `WINIT_X11_SCALE_FACTOR` environment variable to `1`. + Flatpak installs will have this set automatically. +* The file/folder picker doesn't work. + * **Linux:** Make sure that you have Zenity or kdialog installed and available on the `PATH`. + The `DISPLAY` environment variable must also be set. + * **Steam Deck:** Use desktop mode instead of game mode. + * **Flatpak:** The `DISPLAY` environment variable may not be getting passed through to the container. + This has been observed on GNOME systems. + Try running `flatpak run --nosocket=fallback-x11 --socket=x11 com.github.mtkennerly.ludusavi`. +* On Windows 11, when I open the GUI, a console window also stays open. + * This is a limitation of the new Windows Terminal app (https://github.com/microsoft/terminal/issues/14416). + It should be fixed once Windows Terminal v1.17 is released. + In the meantime, you can work around it by opening Windows Terminal from the Start Menu, + opening its settings, and changing the "default terminal application" to "Windows Console Host". +* The GUI won't launch. + * There may be an issue with your graphics drivers/support. + Try using the software renderer instead by setting the `ICED_BACKEND` environment variable to `tiny-skia`. + * You can try prioritizing different hardware renderers + by setting the `WGPU_BACKEND` environment variable to `dx12`, `vulkan`, or `metal`. + * **Flatpak:** You can try forcing X11 instead of Wayland: + `flatpak run --nosocket=wayland --socket=x11 com.github.mtkennerly.ludusavi` + +## Environment variables on Windows +Some of the instructions above mention setting environment variables. +If you're using Windows and not familiar with how to do this, +you can follow these instructions: + +* Open the Start Menu, + search for `edit the system environment variables`, + and select the matching result. +* In the new window, click the `environment variables...` button. +* In the upper `user variables` section, click the `new...` button, + then enter the variable name and value. + If the variable already exists, select it and click `edit...`.