Improves a lot of the language in the readme so that it can be better
understood.
---
README.md | 69 ++++++++++++++++++++++++++-----------------------------
1 file changed, 32 insertions(+), 37 deletions(-)
diff --git a/README.md b/README.md
index c34b638..1d20364 100644
--- a/README.md
+++ b/README.md
@@ -36,14 +36,14 @@ The term "eigen" comes from German, meaning "own". So in a sense, this is *your
### Why just desktop?
-I'm still quite skeptical that you can truly make good applications for platforms so distinct as
-desktop and mobile from a single codebase. I've yet to find any good example.
-
-Seeing as the paradigms of keyboard+mouse driven UIs and of touch driven UIs are so different, you'd
-have to be very careful and thoughtful, and consider all the edge cases of form factor transitions
-and paradigm translations, to write a proper one-codebase-to-rule-them GUI.
-At that point, you might as well just write "native" apps and get proper system integration from the
-get go.
+I'm still quite skeptical that you can use one codebase to make good quality applications for platforms as
+different and diverse as desktop and mobile. I've yet to find a good example.
+
+Seeing as keyboard and mouse driven UIs and touch driven UIs are so different, you'd have to be very thoughtful
+about it and consider all the edge cases of different device form factors and interface constraints, to write a
+proper one-codebase-to-rule-them-all GUI. At that point, you might as well just write "native" apps and get
+proper system integration from the get go.
+
I think a great way to avoid duplicating a lot of business logic is use something like [Kotlin
Multiplatform](https://kotlinlang.org/docs/multiplatform.html) or do what
[Element](https://element.io) is doing and make a library with the core stuff and then call it through FFI on
@@ -54,41 +54,41 @@ develop Eigen!
For now, the major focus will be on Linux (since it's the platform I use), with Windows and macOS
being supported as well, though as a best effort. If anyone wants to help me maintain and test those
-builds, let me know.
+builds, let me know.
I'm also open to making WebAssembly builds, given Slint and the Matrix Rust SDK support it. They are
not a priority, however.
### Why Rust?
First of all, I like the language. I have some criticisms, but I like it. It's interesting and mostly forces
-you to write more "correct" code, be it when handling memory, errors or concurrency, for example.
-It's also quite undeniable that Rust's community and ecosystem are quite big and alive, with lots of competent
-people learning and using it, and tons of quality libraries that can save us work (and probably do it better),
-which is always nice and important for an open-source project.
-And that is perhaps the most relevant factor: there's very complete and well-supported crate for interacting
-with Matrix APIs. [Matrix Rust SDK](https://github.com/matrix-org/matrix-rust-sdk), under the [Matrix
-Foundation](https://matrix.org)'s own jurisdiction, is being used by Element to write the game-changing
-Element X clients and is the reason I even thought of starting this project in the first place.
+you to write "correct" code when, for example handling memory, errors or concurrency.
+It's also quite undeniable that Rust's community and ecosystem is quite big and alive, with lots of competent
+developers using it, and there are tons of quality libraries that can save us work (and probably do it better),
+which is always nice and important for an open-source project.
+And that is probably the most relevant factor: there's a very complete and well-supported library for interacting
+with Matrix servers. [Matrix Rust SDK](https://github.com/matrix-org/matrix-rust-sdk), under the ownership of
+the [Matrix Foundation](https://matrix.org), is being used by Element to write the game-changing Element X
+clients and is the reason I even thought of starting this project in the first place.
### Why Slint?
[![#MadeWithSlint](https://github.com/slint-ui/slint/raw/master/logo/MadeWithSlint-logo-dark.svg)](https://madewithslint.com)
-Rust's GUI ecosystem is quite diverse and rapidly evolving, there are libraries and frameworks of all sorts of
-styles.
+Rust's GUI ecosystem is quite diverse and rapidly evolving; there are libraries and frameworks for all sorts of
+styles.
Before I thought of starting Eigen, I actually worked a bit on
[Spectral](https://gitlab.com/spectral-im/spectral/), a promising but now abandoned Matrix client written in
C++ with [QtQuick/QML](https://en.wikipedia.org/wiki/QML) (which was then forked by the KDE folks into
[NeoChat](https://invent.kde.org/network/neochat)).
-I really liked the idea (and for the most part, the execution) of QML, so when it was time to pick a GUI stack
-for Eigen, I immediately turned to it (in fact, I even started writing Eigen stuff with it; see
+I really liked the idea and execution of QML, so when it was time to pick a GUI stack for Eigen, I immediately
+turned to it (in fact, I even started writing Eigen stuff with it; see commit
[`1e7cbc96`](https://git.sr.ht/~tmpod/eigen/commit/1e7cbc96c47ffd7f22460448ed5bc7fa5c5e316f)). Despite
[qmetaobject-rs](https://github.com/woboq/qmetaobject-rs) and [CXX-Qt](https://github.com/KDAB/cxx-qt) being a
-thing, they felt like a some hack, cobbling Rust and C++ together, and ultimately were quite awkward to work
+thing, they felt like a hack, cobbling Rust and C++ together, and ultimately were quite awkward to work
with async Rust (a fundamental part of Eigen, as mentioned above), because of Qt's own event loop. I had my
-eyes on Slint for a while, but I always saw it as very incomplete weird clone of QML, until the end of last
-year. They made incredible progress during 2023 and when I started playing around with it in December, I was
-quite pleasantly surprised.
+eyes on Slint for a while, but I always saw it as a very incomplete and weird clone of QML, until the end of
+last year. They made incredible progress during 2023 and when I started playing around with it in December, I
+was quite pleasantly surprised.
After [asking around](https://github.com/slint-ui/slint/discussions/4377) about async support, I was satisfied
enough with it and started working on Eigen from the ground up again.
@@ -105,33 +105,28 @@ Discussions are carried out through mailing lists, which also receive
normal-looking tickets, still compatible with e-mail.
I chose it because I like the flow, I like the work sourcehut has been doing and technically it allows for
-easier account-less contributions.
+easier account-less contributions.
Now, I won't delude myself. This is unlikely to work out in the future, if the project gains more
-contributors, but I still think it's a good experiment.
+contributors, but I still think it's a good experiment.
If contributors really don't want to use this system after trying it, I will consider moving to
[Codeberg](https://codeberg.org).
-### How can I contribute?
+### How can I contribute? (patches, bug reports, feature requests)
It's very nice of you to want to contribute, thanks!
Since we are on sourcehut, GitHub-like pull requests are not a thing, but it's very easy!
Take a look at [`CONTRIBUTING.md`](./CONTRIBUTING.md) for all the whats and hows.
-### How can I submit bug reports or suggest new features?
-
-Since we are on sourcehut, GitHub-like issues are not a thing, but it's very easy!
-Take a look at [`CONTRIBUTING.md`](./CONTRIBUTING.md#working-with-sourcehut) for more info.
-
### Why AGPL?
-The Affero GPL is a slightly modified version of regular GNU GPL which also mandates code distribution if the
-software is run and accessible on a server.
+The GNU Affero General Public License is a slightly modified version of the regular GNU GPL which also
+mandates code distribution if the software is run and accessible on a server.
This is to cover the eventuality of making a WebAssembly build of Eigen, since Slint supports it.
## License
-This software is licensed under the [Affero General Public License
-v3](https://www.gnu.org/licenses/agpl-3.0.html), whose full text can also be found in
+This software is licensed under the [GNU Affero General Public License
+v3](https://www.gnu.org/licenses/agpl-3.0.html), the full text of which can be found in
[`COPYING.md`](./COPYING.md).
--
2.43.2
Details how to build Eigen with cargo and run the program.
Outline the dependencies needed to run it and the the issues one
might run into when using Eigen without a keyring, or using KWallet
without libqca-ossl.
ldd proves that Eigen depends on libsqlite3, and libssl+libcrypto
which are part of OpenSSL.
---
README.md | 9 ++++++++-
1 file changed, 8 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 1d20364..efe411a 100644
--- a/README.md
+++ b/README.md
@@ -21,8 +21,15 @@ If you have any good ideas or design skills, hit me up [on Matrix](matrix:u/tmpo
## Usage
-`TBD`
+First, proceed with building Eigen. Install Rust and Cargo, then use `cargo build -r` to compile Eigen in
+release mode. After Eigen has finished being built, you can run the executable by running `./target/release/eigen`.
+
+To run Eigen, you will need OpenSSL and sqlite installed, which you probably already have. Additionally you
+will need a keyring program to securely store passwords, such as gnome-keyring or KWallet. If you're using a
+desktop environment such as GNOME or KDE Plasma, this is probably already set up for you.
+KWallet users may have to install the QCA OSSL plugin, usually under the name `libqca-ossl` or `qca-ossl` in
+your package manager.
## FAQ
--
2.43.2