From 7f48888c143c11850492b037d3a405a5475f5794 Mon Sep 17 00:00:00 2001
From: Alain Emilia Anna Zscheile <fogti+devel@ytrizja.de>
Date: Tue, 31 Dec 2024 20:01:49 +0100
Subject: [PATCH] docs(INSTALL): native run-time dependencies

---
 INSTALL.md                    | 26 ++++++++++++++++++++++++++
 crates/topola-egui/Cargo.toml |  9 +++++++--
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/INSTALL.md b/INSTALL.md
index cd80f3c..d9e7695 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -103,6 +103,32 @@ You can then invoke the application from your terminal by running
 topola-egui
 ```
 
+#### Native run-time dependencies
+
+On Linux and BSDs, the `egui` depends on the native graphics libraries (X11, Wayland),
+and requires [GNOME `zenity`](https://gitlab.gnome.org/GNOME/zenity) when using `xdg-portal`
+(which is the default) as the backend for [`rfd`](https://docs.rs/rfd) (which we use for file chooser dialogs).
+
+If the Topola GUI crashes on startup (no window is shown), necessary graphics libraries (X11, Wayland)
+might be missing. Note that running `ldd` on the `topola-egui` executable doesn't show these,
+they are loaded dynamically (via some `dlopen`-like mechanism) on startup.
+
+If no file chooser dialog is shown (e.g. when trying to Open a DSN file),
+and, if `topola-egui` is started from a terminal, an error message like:
+```
+[2025-01-01T01:16:17Z ERROR rfd::backend::xdg_desktop_portal] pick_file error No such file or directory (os error 2)
+```
+is emitted (which should only happen on Linux/BSDs and similar environments), then
+[GNOME `zenity`](https://gitlab.gnome.org/GNOME/zenity) is not installed, but is required
+for the file choser to work.
+Alternatively, one might try the alternative `gtk3` backend for `rfd` by enabling the `gtk3`
+feature of `topola-egui`, e.g.
+```
+cargo build -p topola-egui --release --no-default-features --features disable_contracts --features gtk3
+```
+This is mostly interesting for people who want to package Topola, and allow exposing features
+(e.g. Gentoo Linux / Portage)
+
 #### Building and running without installing
 
 If you chose not to install the GUI application, you can build and run
diff --git a/crates/topola-egui/Cargo.toml b/crates/topola-egui/Cargo.toml
index 801c56d..9444e2c 100644
--- a/crates/topola-egui/Cargo.toml
+++ b/crates/topola-egui/Cargo.toml
@@ -9,8 +9,10 @@ version = "0.1.0"
 edition = "2021"
 
 [features]
-default = ["disable_contracts"]
+default = ["disable_contracts", "xdg-portal"]
 disable_contracts = ["topola/disable_contracts"]
+gtk3 = ["rfd/gtk3"]
+xdg-portal = ["rfd/xdg-portal"]
 
 [dependencies]
 derive-getters.workspace = true
@@ -21,7 +23,6 @@ icu_experimental = "0.2"
 icu_locale_core = "2.0.0-beta1"
 log = "0.4"
 petgraph.workspace = true
-rfd = "0.15"
 rstar.workspace = true
 serde.workspace = true
 serde_json.workspace = true
@@ -41,6 +42,10 @@ version = "0.29"
 default-features = false
 features = ["accesskit", "default_fonts", "glow", "persistence"]
 
+[dependencies.rfd]
+version = "0.15"
+default-features = false
+
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 futures-lite = "2.5"
 env_logger = "0.11"