mirror of https://codeberg.org/topola/topola.git
docs(install): copyedit and rearrange sections
This commit is contained in:
Mikolaj Wielgus
parent
51e5ccac2e
commit
f3389e4c9c
140
INSTALL.md
140
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue