berkus
/
topola
mirror of https://codeberg.org/topola/topola.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs(install): copyedit and rearrange sections

This commit is contained in:
Mikolaj Wielgus 2025-01-01 21:14:48 +01:00
parent 51e5ccac2e
commit f3389e4c9c
1 changed files with 76 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
INSTALL.md
View File

@ -11,8 +11,8 @@ SPDX-License-Identifier: MIT
### Prerequisites ### Prerequisites
Building Topola from source requires Building Topola from source requires
[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and
[cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) [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 to be installed on your system. Follow the instructions in the above links to
obtain these. obtain these.
@ -30,11 +30,14 @@ Change your working directory to your clone of Topola's repository:
### Command-line application ### Command-line application
Topola has a command-line application written the help of the Topola has a command-line application written with the help of the
[clap](https://docs.rs/clap/latest/clap/) library. [`clap`](https://docs.rs/clap/latest/clap/) library.
(If you do not want to install new software on your system, skip now to the #### Installation from source
[Debug build](#debug-build) subsection.)
(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 Run the following command to build and install the Topola's command-line
application: application:
@ -82,21 +85,35 @@ In the newly opened file dialog, choose the file named
### Egui graphical user interface application ### Egui graphical user interface application
Topola has a graphical user interface (GUI) application written using the Topola has a graphical user interface (GUI) application written using the
[egui](https://github.com/emilk/egui/) library and its paired [`egui`](https://github.com/emilk/egui/) library and its paired
[eframe](https://github.com/emilk/egui/tree/master/crates/eframe) framework. [`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 Due to technical constraints, these libraries have multiple runtime dependencies
[Debug build](#debug-build-1) subsection.) 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: The following command will build and install the Topola's GUI application:
cargo install --locked --path crates/topola-egui 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 topola-egui
#### Debug build #### Native debug build
If you do not want to install new software on your system, or are interested in 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 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 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: following command:
cargo run -p topola-egui 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 #### 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 [Trunk](https://trunkrs.dev/). If you have
[cargo-binstall](https://github.com/cargo-bins/cargo-binstall) [cargo-binstall](https://github.com/cargo-bins/cargo-binstall)
on your system, you can install Trunk from binary with 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 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 trunk serve
This will work both with and without having the GUI application #### Troubleshooting unmanaged runtime dependencies
installed.
##### 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 ### Automated tests
@ -162,29 +177,26 @@ To execute these, run
cargo test cargo test
Automated tests are run in `debug` profile.
### Contracts ### Contracts
(The feature described in this section is enabled only when using nightly Rust (The feature described in this section is currently used only for debugging and
and only under `debug` profile. If you are not interested in debugging, you can is enabled only when using nightly Rust. If you are not interested in debugging,
skip this section altogether.) you can skip this section altogether.)
When trying to locate the source of a bug, it may be helpful to enable 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 [contracts](https://en.wikipedia.org/wiki/Design_by_contract) (yes, this
Wikipedia article needs improvement), which are nothing else but Wikipedia article needs improvement), which are nothing else but somewhat
somewhat enchanced assertions. enchanced assertions.
Unfortunately, the Unfortunately, the
[contracts](https://docs.rs/contracts/latest/contracts/) library which [contracts](https://docs.rs/contracts/latest/contracts/) library which we have
we have been using enforces post-conditions via closures, which have been using enforces post-conditions via closures, which have deal-breaking
deal-breaking limitations. To bypass these we have forked and modified limitations. To bypass these we have forked and modified it to use `try` blocks
it to use `try` blocks instead. The fork is vendored in the instead. The fork is vendored in the [vendored/contracts/](vendored/contracts/)
[vendored/contracts/](vendored/contracts/) directory. directory.
However, `try` blocks are not present in stable Rust yet, so to use However, `try` blocks are not present in stable Rust yet, so to use these you
these you need to set up your toolchain to use a nightly version of need to set up your toolchain to use a nightly version of Rust.
Rust.
#### Nightly Rust #### Nightly Rust
@ -198,14 +210,14 @@ You can go back to stable with
#### Enabling contracts #### Enabling contracts
To enable contracts, simply add a `--no-default-features` switch. This To enable contracts, simply add a `--no-default-features` switch. This switches
switches off a default feature that prevents contracts from executing. off a default feature that prevents contracts from executing. For example, to
For example, to build tests with contracts, simply run build tests with contracts, simply run
cargo test --no-default-features cargo test --no-default-features
Of course, you can enable contracts for any build target. For instance, Of course, you can enable contracts for any build target. For instance, the
the following command will build the Egui application with debug profile following command will build the Topola's GUI application with debug profile and
and contracts enabled: contracts enabled:
cargo build -p topola-egui --no-default-features cargo build -p topola-egui --no-default-features