From f3389e4c9c36d4e18c3f7563717485f7e96812f7 Mon Sep 17 00:00:00 2001 From: Mikolaj Wielgus Date: Wed, 1 Jan 2025 21:14:48 +0100 Subject: [PATCH] docs(install): copyedit and rearrange sections --- INSTALL.md | 140 +++++++++++++++++++++++++++++------------------------ 1 file changed, 76 insertions(+), 64 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 0f295cb..969883c 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -11,8 +11,8 @@ SPDX-License-Identifier: MIT ### Prerequisites Building Topola from source requires -[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and -[cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) +[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and +[Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) to be installed on your system. Follow the instructions in the above links to obtain these. @@ -30,11 +30,14 @@ Change your working directory to your clone of Topola's repository: ### Command-line application -Topola has a command-line application written the help of the -[clap](https://docs.rs/clap/latest/clap/) library. +Topola has a command-line application written with the help of the +[`clap`](https://docs.rs/clap/latest/clap/) library. -(If you do not want to install new software on your system, skip now to the -[Debug build](#debug-build) subsection.) +#### Installation from source + +(Topola can be built and run without installation. If you do not want to install +new software on your system, skip now to the [*Debug build*](#debug-build) +subsection.) Run the following command to build and install the Topola's command-line application: @@ -82,21 +85,35 @@ In the newly opened file dialog, choose the file named ### Egui graphical user interface application Topola has a graphical user interface (GUI) application written using the -[egui](https://github.com/emilk/egui/) library and its paired -[eframe](https://github.com/emilk/egui/tree/master/crates/eframe) framework. +[`egui`](https://github.com/emilk/egui/) library and its paired +[`eframe`](https://github.com/emilk/egui/tree/master/crates/eframe) framework. +For displaying dialog boxes, Topola's GUI application uses the +[Rusty File Dialogs](https://docs.rs/rfd/latest/rfd/) library. -(If you do not want to install new software on your system, skip now to the -[Debug build](#debug-build-1) subsection.) +Due to technical constraints, these libraries have multiple runtime dependencies +that are not managed by Cargo, and as such, it is impossible to determine +whether these dependencies have been satisfied during compilation, but only once +the application has been launched. Because of that, Topola may crash on startup, +or have the file selection dialog not appear. If you encounter any problems, +read the +[*Troubleshooting unmanaged runtime dependencies*](#troubleshooting-unmanaged-runtime-dependencies) +subsection. + +#### Native installation from source + +(Topola can be also built and run without installation. If you do not want to +install new software on your system, skip now to the +[*Native debug build*](#native-debug-build) subsection.) The following command will build and install the Topola's GUI application: cargo install --locked --path crates/topola-egui -You can then start the application from your terminal by running +You can then launch the application from your terminal by running topola-egui -#### Debug build +#### Native debug build If you do not want to install new software on your system, or are interested in debugging or developing Topola, you can build a debug executable of the Topola's @@ -104,40 +121,14 @@ GUI application inside your working directory by running cargo build -p topola-egui -Once built, you can start the application from the debug executable with the +Once built, you can launch the application from the debug executable with the following command: cargo run -p 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) - #### Running Topola in Web browser -Topola's GUI application can be built to and run in a Web browser using +Topola's GUI application can be built to run in a Web browser using [Trunk](https://trunkrs.dev/). If you have [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) on your system, you can install Trunk from binary with @@ -148,12 +139,36 @@ Alternatively, you can build Trunk from source by running cargo install trunk -To build and open Topola in your browser, run +To build and open the Topola's GUI application in your browser, run trunk serve -This will work both with and without having the GUI application -installed. +#### Troubleshooting unmanaged runtime dependencies + +##### Crash on startup + +If the Topola's GUI application crashes on startup (no window is shown), +necessary libraries for graphics and windowing (such as X11 and Wayland) may +be missing. Note that running `ldd` on the `topola-egui` executable does not +show these, as they are loaded dynamically (via some `dlopen`-like mechanism) +on startup. + +##### No file selection dialog appears + +If no file selection dialog appears when trying to open a file, then this is +most likely because you do not have +[Zenity](https://gitlab.gnome.org/GNOME/zenity) installed on your system. In +this case, an error similar to the following should be emitted in your terminal: + +``` +[2025-01-01T01:16:17Z ERROR rfd::backend::xdg_desktop_portal] pick_file error No such file or directory (os error 2) +``` + +Zenity is needed because it is used by the default `xdg-portal` backend of +Rusty File Dialogs. As an alternative, you can try its other backend, `gtk3`, by +building `topola-egui` with the following command: + + cargo build -p topola-egui --release --no-default-features --features disable_contracts --features gtk3 ### Automated tests @@ -162,29 +177,26 @@ To execute these, run cargo test -Automated tests are run in `debug` profile. - ### Contracts -(The feature described in this section is enabled only when using nightly Rust -and only under `debug` profile. If you are not interested in debugging, you can -skip this section altogether.) +(The feature described in this section is currently used only for debugging and +is enabled only when using nightly Rust. If you are not interested in debugging, +you can skip this section altogether.) When trying to locate the source of a bug, it may be helpful to enable [contracts](https://en.wikipedia.org/wiki/Design_by_contract) (yes, this -Wikipedia article needs improvement), which are nothing else but -somewhat enchanced assertions. +Wikipedia article needs improvement), which are nothing else but somewhat +enchanced assertions. Unfortunately, the -[contracts](https://docs.rs/contracts/latest/contracts/) library which -we have been using enforces post-conditions via closures, which have -deal-breaking limitations. To bypass these we have forked and modified -it to use `try` blocks instead. The fork is vendored in the -[vendored/contracts/](vendored/contracts/) directory. +[contracts](https://docs.rs/contracts/latest/contracts/) library which we have +been using enforces post-conditions via closures, which have deal-breaking +limitations. To bypass these we have forked and modified it to use `try` blocks +instead. The fork is vendored in the [vendored/contracts/](vendored/contracts/) +directory. -However, `try` blocks are not present in stable Rust yet, so to use -these you need to set up your toolchain to use a nightly version of -Rust. +However, `try` blocks are not present in stable Rust yet, so to use these you +need to set up your toolchain to use a nightly version of Rust. #### Nightly Rust @@ -198,14 +210,14 @@ You can go back to stable with #### Enabling contracts -To enable contracts, simply add a `--no-default-features` switch. This -switches off a default feature that prevents contracts from executing. -For example, to build tests with contracts, simply run +To enable contracts, simply add a `--no-default-features` switch. This switches +off a default feature that prevents contracts from executing. For example, to +build tests with contracts, simply run cargo test --no-default-features -Of course, you can enable contracts for any build target. For instance, -the following command will build the Egui application with debug profile -and contracts enabled: +Of course, you can enable contracts for any build target. For instance, the +following command will build the Topola's GUI application with debug profile and +contracts enabled: cargo build -p topola-egui --no-default-features