Development¶
For working on rettui: where things are in the code, and how builds and releases are made. To build it yourself, see Installing.
Code layout¶
The protocol modules each sit on one of the submodules. The UI modules are split
by tab, and app/ and ui/ mirror each other. The web UI drives the same App
state as the TUI.
| Module | What it does | Built on |
|---|---|---|
net/ |
Network actor, on its own threads so heavy traffic can't hold up either UI: runtime, announces, paths and keys, commands and events; rngit requests over Links (git) |
rsReticulum, rngit-rs |
lxmf/ |
Sending, receiving and propagation node sync | rsLXMF |
nomad/ |
Page and file fetching, Micron parsing and layout, page cache, hosting a node and its pages | rsReticulum |
rrc/ |
RRC wire format, hub replies, hub sessions | rsReticulum |
reticulum/ |
Reticulum config file: the options it has, editing it in place, and checking it | rsReticulum |
app/ |
Application state per tab (messages, channels, network, browser, node, reticulum, repos), the page editor's formatting (format), notifications (notify) and input routing |
|
ui/ |
Drawing per tab, plus the sidebar, footer and prompt (chrome), the keys of each mode for the footer and the ? list (keys), and the text editors |
ratatui |
term/ |
Text input, the editors' text area, selection, clipboard, images (Kitty, Sixel, iTerm2 or half blocks), desktop notifications (desktop) |
ratatui-image, notify-rust |
desktop/ |
The desktop app (rettui-desktop): the web UI in a window of its own, a package of its own on Tauri |
Tauri |
web/ |
Web UI: HTTP API, login, live updates and notifications, and the page's HTML/CSS/JS, service worker, font and logo (web/assets) |
axum |
main.rs only calls lib.rs, which has the command line and starts the
TUI or the web UI; the Android app loads the same library and
calls it through android.rs (JNI). cli.rs has the shell commands (send, listen, sync, fetch), and
store.rs and config.rs hold what is saved to disk, and app/saver.rs
writes the store and chat history in the background.
Releases and CI¶
The workflows are in .github/workflows:
- CI (ci.yml) runs on every pull request:
- a formatting check: run
cargo fmtbefore committing (rustfmt.tomlhas rettui's style;cargo fmt --checksays what it would change); - Clippy, with warnings as errors (and the desktop app, which needs WebKitGTK, checked on Linux);
- the tests on Linux, Windows and macOS.
- Build (build.yml) builds the binaries for every platform in the Installing table without making a release:
- Run it from Actions > Build > Run workflow (tick Linux only for just the Linux binaries).
- Download the archives from the run's Artifacts.
- They're named after the version and commit, for example
rettui-v1.2.0-a4e545b-x86_64-unknown-linux-gnu.tar.gz. - Desktop (desktop.yml) builds
the desktop app (
desktop/,rettui-desktop) for the same platforms as Build: - Run it from Actions > Desktop > Run workflow (tick Linux only for
just the Linux builds), or push to
feature/desktop, and download from the run's Artifacts. - It runs rettui in the same process and shows its web UI in the
system's webview (WebKitGTK on Linux, WebView2 on Windows, WKWebView
on macOS). It's a package of its own so that
rettuinever links them:cargo buildat the top builds rettui alone. - Signing is optional. With none of the secrets below set (the
default, and for forks and pull requests) the installers are built
unsigned and everything else works. Set them under the repository's
Settings > Secrets and variables > Actions to sign:
- macOS:
APPLE_CERTIFICATE(a Developer ID Application.p12, base64),APPLE_CERTIFICATE_PASSWORDandAPPLE_SIGNING_IDENTITY(for exampleDeveloper ID Application: Name (TEAMID)); to notarize too,APPLE_ID,APPLE_PASSWORD(an app-specific password) andAPPLE_TEAM_ID. - Windows:
WINDOWS_CERTIFICATE(a code signing.pfx, base64) andWINDOWS_CERTIFICATE_PASSWORD.
- macOS:
- Its identity, backup and pipe interface screens are a window of their
own, a page bundled in the app (
desktop/ui/), not part of the web UI. Their commands (desktop/src/manage.rs) are given only to that window (desktop/capabilities/manage.json), and callrettui::manage(src/web/desktop.rs), which works only in the desktop app. Don't add them to the web UI's routes. A new command needs a permission indesktop/build.rsand the capability. - Closing its window leaves rettui running, with a tray icon to open
it again or quit (Keep running when closed, on; Minimize to tray,
off). On Linux the tray needs libayatana-appindicator, which the
.debdepends on and the AppImage and Flatpak carry (the Flatpak builds it fromdesktop/flatpak/shared/, copied from Flathub's shared modules). - It makes, unsigned: a
.deb(and on x86-64 an AppImage), a Flatpak bundle (.flatpak, on the GNOME runtime, fromdesktop/flatpak/) and a plain.tar.gzfor Linux, an installer.exefor Windows and a.dmgfor macOS, named likerettui-desktop-v1.11.0-x86_64-unknown-linux-gnu.deb. - It also packs the program alone for every platform
(
rettui-desktop-v1.11.0-<target>.tar.gz,.zipfor Windows), as Build packsrettui: the desktop app's Install (in Status) updates itself from those, as rettui does. Packages (.deb, the AUR) leave updating to the package manager, and the Flatpak and AppImage are replaced whole. macOS asks to allow an unsigned app in System Settings > Privacy & Security, and Windows SmartScreen warns before running it. - Android (android.yml) builds a test
APK of the Android app (
android/): - Run it from Actions > Android > Run workflow, or push to
feature/android. - Download the APK from the run's Artifacts.
- It cross-builds rettui with the NDK (
android/build-rust.sh), then runs Gradle. TheANDROID_KEYSTOREsecret, if set, signs every build with one key. - Each build's version code is the minutes since late 2023, so any build, test or release, installs over an earlier one.
- The Release workflow calls it for a release build (not debuggable,
so
adbcan't read the app's files), signed with the same key. - Release (release.yml) runs when a
tag starting with
vis pushed. Before tagging, add the release to CHANGELOG.md under a## v1.7.0heading (a prerelease,v1.7.0-rc.1, may have its own, or uses the release's). It: - checks the tag matches the version in
Cargo.toml, and thatCHANGELOG.mdhas its section; - builds every platform with the Build workflow, the desktop app with
the Desktop workflow, and the Android app
(
rettui-v1.7.0-android-arm64-v8a.apk) with the Android workflow; - pushes the Docker image to
ghcr.io, using those Linux binaries (the Dockerfile'sprebuiltstage); - makes Debian packages of the Linux binaries
(
.github/scripts/package-deb.sh):rettui_1.7.0_amd64.debandrettui_1.7.0_arm64.deb; - for a release (not a prerelease), writes a Homebrew formula
(
rettui.rb, by.github/scripts/homebrew-formula.sh) and the AUR'srettui-binandrettui-desktop-binpackages (PKGBUILDandPKGBUILD-desktop, by.github/scripts/aur-pkgbuild.sh) from the checksums; - creates a GitHub release with the archives, the packages, the
desktop app's installers, the APK,
SHA256SUMS,rettui.rbandPKGBUILD, and the tag's section ofCHANGELOG.md(printed by.github/scripts/release-notes.sh v1.7.0) as its notes, with each###subsection folded away in a<details>block (--collapse) so the assets are near the top, and the Docker image's name; - for a release, publishes the formula to the Homebrew tap and the package to the AUR (see Homebrew and the AUR below).
A tag containing a hyphen (v1.3.0-rc.1) makes a prerelease. Its image
gets only the version tag, not latest. Run workflow on a version tag
does the same as pushing it.
- Prerelease (prerelease.yml)
makes a development prerelease of dev, on command: Actions >
Prerelease > Run workflow, on dev. It:
1. picks the version it leads up to: the one typed in, else
Cargo.toml's if that isn't released yet, else the next minor
version after the newest release (1.10.0 after v1.9.0);
2. numbers it from that version's earlier ones: v1.10.0-dev.1, then
v1.10.0-dev.2;
3. sets that version in Cargo.toml and Cargo.lock, and adds a
section for it to CHANGELOG.md (what it is, a link to the commits
since the last release, then the version's own section if there is
one yet), all by .github/scripts/prepare-prerelease.sh;
4. commits that and tags the commit, without changing dev;
5. starts the Release workflow on the tag, which builds and publishes
it as a prerelease (no Homebrew or AUR, no latest image).
Update checks leave prereleases out unless Include prereleases in
update checks is on, so they're mostly for those who download one.
- Branch image (docker-branch.yml)
runs on every push to a branch other than main. It builds the Linux
binaries and pushes an image tagged with the branch name: pushing to
dev gives ghcr.io/zevaryx/rettui:dev, and feature/x gives
:feature-x. A newer push to the same branch cancels an unfinished run.
- Wiki (wiki.yml)
copies wiki/ to this wiki when it changes on main or dev, or when
run from Actions > Wiki > Run workflow. Edit the pages in wiki/, not here: the
next publish replaces the wiki with them.
- Docs (docs.yml)
builds the documentation site from
wiki/ with Zensical, and publishes it to GitHub Pages from main. Pull
requests that change wiki/ only build it: a link to a page or heading
that doesn't exist, or a page left out of _Sidebar.md, fails the build.
python3 docs/build.py serve shows it locally (see
docs/README.md).
Both image workflows push through docker.yml.
To release, bump version in Cargo.toml, commit, then:
Homebrew and the AUR¶
The Release workflow's last job, Homebrew and AUR, publishes a release
(not a prerelease) to both, from the release's SHA256SUMS. Each half
runs once its secrets are set (Settings → Secrets and variables →
Actions), and is skipped with a notice until then. Running it again
(Re-run jobs) pushes nothing new, so it's safe to re-run after fixing a
secret.
- Homebrew: the tap is a GitHub repository named
homebrew-rettui(zevaryx/homebrew-rettui; another, asowner/name, in the repository variableHOMEBREW_TAP). The secretHOMEBREW_TAP_DEPLOY_KEYis the private half of an SSH key whose public half is the tap's deploy key, with write access (tap's Settings → Deploy keys). The job writes the formula toFormula/rettui.rb(.github/scripts/publish-homebrew.sh). Thenbrew install zevaryx/rettui/rettuiinstalls rettui, andbrew upgradethe next release. - AUR: the secret
AUR_SSH_PRIVATE_KEYis the private half of an SSH key whose public half is on the AUR account (My Account → SSH Public Key);AUR_USERNAMEandAUR_EMAILare the PKGBUILD's maintainer line and its commits' author, both public on the AUR. The job checks the AUR's host key against the fingerprint aur.archlinux.org publishes, writes.SRCINFOwithmakepkg(in an Arch Linux container), and pushes torettui-binandrettui-desktop-bin(.github/scripts/publish-aur.sh); the first push makes each package. Thenyay -S rettui-bin(or any AUR helper) installs rettui, andyay -S rettui-desktop-binthe desktop app.
By hand, from any release's SHA256SUMS: homebrew-formula.sh and
aur-pkgbuild.sh write the formula and the package, and
publish-homebrew.sh and publish-aur.sh push them, as the job does.