Skip to content

Commit 5be9135

Browse files
Piliiiclaude
andcommitted
fix(linux): avoid NVIDIA EGL atexit segfault on quit
libEGL_nvidia registers an atexit handler that tears down EGL state and segfaults inside libnvidia-eglcore on some driver versions, run after main() returns from g_application_run() — by which point the GTK window and Flutter engine are already shut down cleanly. Skip that handler chain via _exit() instead of a normal return. Documents a second, related coredump-on-quit variant (SIGABRT via a libepoxy assertion) that is a genuine open upstream Flutter engine bug (flutter/flutter#192873) and is not fixable from this repo. Co-Authored-By: Claude Sonnet 5 <[email protected]>
1 parent ce565b0 commit 5be9135

2 files changed

Lines changed: 168 additions & 4 deletions

File tree

‎CLAUDE.md‎

Lines changed: 156 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,10 @@ rename those, they're just library identifiers.
1111
## Product shape
1212

1313
- **Clients (all Flutter/Dart, one codebase):** website, native Linux desktop,
14-
native Android. **No Windows, no Electron** (the owner refuses Electron on
15-
privacy grounds — don't propose it).
14+
native Android. **No Electron** (the owner refuses Electron on privacy
15+
grounds — don't propose it). Native Windows desktop support is planned (see
16+
roadmap v1.9.0) — Flutter's Windows target is a native Win32 build, not
17+
Electron, so it doesn't conflict with that rule.
1618
- **Notes:** markdown text. Desktop = notes list on the left, editor on the
1719
right. Mobile = staggered 2-column masonry grid of cards (body preview only
1820
when no title; title + body when title exists, variable height).
@@ -471,7 +473,117 @@ flutter build apk --release --target-platform android-arm64 # release APK (arm
471473
were deleted as dead code once nothing referenced them.
472474
- `flutter analyze` clean across the whole app after each change.
473475

474-
24. **TODO — versioned roadmap, grouped by dependency and theme:**
476+
24. **Server download links were broken + no arm64 server build existed** — DONE:
477+
- **Root cause**: the website's Server Setup "Binary install" card told users to
478+
`curl` `https://librenotes.ayopili.com/dl/server`, but that short link
479+
redirected to `github.com/.../releases/latest` — an HTML release-notes
480+
page, not a binary. Confirmed live: `curl -L` on it downloads the page,
481+
and the shown `chmod +x librenotes-server` then runs against that HTML
482+
file. The instructions were non-functional for everyone, on any
483+
architecture, independent of the arm64 gap below. Separately, the copy
484+
also said "Replace linux-x86_64 with linux-arm64 if on a Raspberry Pi"
485+
even though the shown command never contained that string anywhere, and
486+
`build-server` in `release.yml` only ever ran on `ubuntu-latest`
487+
(x86_64) with no cross-compile step — no arm64 asset has ever been
488+
published, so the instruction was false on a *real* Raspberry Pi (which
489+
is arm64), undermining the "5 minutes on a Raspberry Pi" pitch repeated
490+
in both the Server Setup and Download sections. On top of that, the
491+
real release asset was never a bare binary to begin with -
492+
`scripts/package-server.sh` produces a `.tar.gz` with the binary,
493+
`install.sh` (sets up a systemd service under a dedicated
494+
`librenotes` user), `backup.sh`, and a bundled `libsqlite3.so` - but the
495+
website's 3-step flow described curl-ing a raw executable and running
496+
it in the foreground, which was never what shipped.
497+
- **Fix**: `build-server` in `release.yml` is now a 2-leg matrix
498+
(`ubuntu-latest`/x86_64, `ubuntu-24.04-arm`/arm64 - GitHub's free hosted
499+
arm64 runners, no QEMU needed), each uploading a differently-named
500+
artifact (`server-tarball-x86_64` / `server-tarball-arm64`) merged into
501+
the same release via the existing `merge-multiple: true` download step.
502+
`scripts/package-server.sh` normalizes `uname -m` (`aarch64` → `arm64`)
503+
and **drops the version number from the tarball filename** (now
504+
`librenotes-server-linux-<arch>.tar.gz`, version still embedded inside
505+
as a `VERSION` file) specifically so `website/vercel.json`'s `/dl/server`
506+
and new `/dl/server-arm64` redirects can point at GitHub's *stable*
507+
`/releases/latest/download/<exact-filename>` URLs without going stale
508+
every time `server/pubspec.yaml`'s version bumps (see item above on
509+
that version being independent of the app's). `ServerSetupSection.js`'s
510+
Binary steps were rewritten to match the real flow: download + `tar
511+
-xzf` the tarball, `cd` into it, `sudo bash install.sh` (which itself
512+
prints the token, with a `sudo cat /var/lib/librenotes/token` fallback
513+
shown too), then connect the app - and the arm64 instruction now points
514+
to the actual `/dl/server-arm64` link instead of an unmatched
515+
find-replace string.
516+
- **Not yet verified against a real tagged release**: everything here is
517+
implemented and build-clean (`npm run build`, bash syntax, YAML
518+
structure all checked), but the actual CI matrix job and the new
519+
`/dl/server*` redirects can only be confirmed once a real `v*` tag is
520+
pushed and `release.yml` runs for real - not done as part of this
521+
session per the "never push without being asked" rule. Until the next
522+
tagged release publishes assets under the new version-less filenames,
523+
`/dl/server` and `/dl/server-arm64` will 404 (the currently-live
524+
`v1.5.0` release still has the old versioned filename,
525+
`librenotes-server-0.1.0-linux-x86_64.tar.gz`).
526+
- **Follow-up refinements, same session**: step 1's download command is
527+
now a true one-liner - `curl -L <url> | tar -xzf -` piped directly,
528+
no intermediate `.tar.gz` file/filename at all (considered a shorter
529+
output filename like `ln-srvr.tar.gz` instead, but that doesn't fix
530+
what actually causes the wrap - the URL length, not the filename -
531+
and a cryptic name reads worse for a command meant to be pasted as
532+
root). Also: `install.sh` had **no non-systemd guard** - it would
533+
partially install (create the `librenotes` user, copy files, write the
534+
data dir) before dying uninformatively on `systemctl: command not
535+
found` on Alpine/Void/Devuan/etc. Added an early check for
536+
`/run/systemd/system` (the reliable "is systemd actually PID 1" test,
537+
not just "is `systemctl` on PATH") right after the root check, so it
538+
now fails immediately with a pointer to the Docker image instead -
539+
Docker already works on any distro regardless of init system, so that
540+
stays the actual answer for non-systemd hosts rather than this project
541+
taking on separate OpenRC/runit/sysvinit unit files to maintain.
542+
543+
25. **Linux desktop coredump on quit (NVIDIA)** — PARTIALLY FIXED:
544+
- **Symptom**: closing the desktop app on an NVIDIA (proprietary driver)
545+
system reliably produces a `systemd-coredump` entry, confirmed against
546+
a real device (`archpp`, driver `615.71.09`) on 2026-09-29. Two distinct
547+
crash signatures were observed, non-deterministically depending on
548+
shutdown timing:
549+
1. `SIGSEGV` inside `libnvidia-eglcore.so`, reached via an
550+
atexit-registered handler in `libEGL_nvidia.so` that runs *after*
551+
`main()` returns from `g_application_run()` — i.e. after the GTK
552+
window and Flutter engine have already shut down cleanly.
553+
2. `SIGABRT` from a libepoxy assertion
554+
(`epoxy_get_proc_address: ... "Couldn't find current GLX or EGL
555+
context"`), preceded by a `Gdk-WARNING: eglMakeCurrent failed`,
556+
happening *during* window teardown rather than after.
557+
- **Fix (variant 1 only)**: `clients/app/linux/runner/main.cc` now calls
558+
`_exit()` right after `g_application_run()` returns, instead of letting
559+
`main()` return normally. This skips libc's atexit handler chain
560+
entirely (harmless — the window and engine are already torn down by
561+
that point), matching the same workaround independently arrived at by
562+
another Flutter-Linux project hitting an identical trace
563+
(`Nihmar/Niman` issue #108 / PR #113).
564+
- **Variant 2 is a genuine, currently-unfixed upstream Flutter engine
565+
bug — not fixable from this repo.** It's
566+
[flutter/flutter#192873](https://github.com/flutter/flutter/issues/192873)
567+
("[Linux] Potential crash in redraw_cb"), filed 2026-09-16 and still
568+
open as of Flutter 3.47.1 (latest stable, Aug 2026 — this project is
569+
still on 3.32.2). Root cause: `fl_view_present_layers()` schedules a
570+
GTK-thread redraw via `g_idle_add()` on the raster thread, but nothing
571+
stops `gtk_widget_destroy()` from tearing down the window concurrently
572+
on the main thread; if the idle callback loses the race it calls
573+
`eglMakeCurrent` against an already-destroyed EGL surface, which fails
574+
and sends libepoxy into an assertion-triggered `abort()`. This is
575+
compiled into the Flutter SDK's own `libflutter_linux_gtk.so`, entirely
576+
outside this repo's source, and the abort happens *before* `main()`
577+
would return — so the variant-1 fix above cannot reach it. No app-level
578+
workaround is known; resolving it requires an upstream engine fix and a
579+
Flutter SDK bump once one lands.
580+
- **Net effect**: quitting the desktop app on NVIDIA may still
581+
occasionally coredump (variant 2) until upstream Flutter fixes
582+
#192873, even though variant 1 is resolved. Neither variant loses data
583+
or affects the running app — both happen strictly during/after
584+
shutdown that has already completed from the user's perspective.
585+
586+
26. **TODO — versioned roadmap, grouped by dependency and theme:**
475587

476588
**v1.6.0 — Packaging & sync infra.** Distribution reach plus the two
477589
remaining infra gaps.
@@ -538,6 +650,23 @@ flutter build apk --release --target-platform android-arm64 # release APK (arm
538650
- **Tearable note tabs on desktop**: let a note be dragged out of the main
539651
app window into its own separate window (tab-tear-off, like a browser
540652
tab), so multiple notes can be viewed/edited side by side on desktop.
653+
- **Windows desktop support**: add `windows` as a native Flutter desktop
654+
target alongside Linux (`flutter create --platforms=windows .` on the
655+
`clients/app/` project, then the usual `windows/` runner scaffold).
656+
Decided 2026-09-29: previously excluded, revisited because both original
657+
blockers are gone — the owner is setting up a Windows 10 VM on Arch
658+
(via `virt-manager`/QEMU) to build/test against directly instead of
659+
shipping blind off CI output, and the SmartScreen unsigned-binary
660+
warning (no code-signing cert) is an accepted tradeoff, not a blocker.
661+
`hotkey_manager`, `window_manager`, and `flutter_secure_storage`
662+
(Windows Credential Manager backend) all already support Windows, so
663+
quick-capture and the keyring-backed DEK (`local_key_manager.dart`)
664+
should port with little change; the Wayland/X11-specific quick-capture
665+
caveats (item 19) don't apply. Distribute an unsigned `.exe`/`.msix` via
666+
GitHub releases (new `release.yml` matrix leg) rather than committing
667+
to a signed release track up front. Still needs: a CI build leg on
668+
`windows-latest`, packaging script, and real manual testing in the VM
669+
before calling it done.
541670

542671
**Not version-gated — do anytime, no release needed.**
543672
- **awesome-selfhosted submission**: submit a PR to
@@ -564,6 +693,20 @@ flutter build apk --release --target-platform android-arm64 # release APK (arm
564693
build of the same version. Generate one keystore, store it
565694
base64-encoded as a GitHub Actions secret, and have `build-android` in
566695
`release.yml` use it instead of the debug config.
696+
- **Google Play Store submission**: planned, as an additional Android
697+
distribution channel alongside F-Droid, GitHub Releases, and AUR — not
698+
a replacement for any of them. The app itself doesn't need to change to
699+
qualify (already Play-Services/Firebase/tracker-free per the F-Droid
700+
audit); this is purely a distribution-channel addition. Depends on the
701+
"Persist a real Android release keystore in CI" item above — Play
702+
requires a stable app signing key across updates (either a
703+
self-managed upload key + Play App Signing, or bring-your-own-key), so
704+
the same keystore work needed to fix GitHub Release APK upgrades should
705+
be done first rather than minting a separate Play-only key. Also needs:
706+
a Google Play Console developer account ($25 one-time fee), a privacy
707+
policy page (the website already exists — could host it there), and
708+
Play's data-safety form filled out honestly (should be easy given
709+
there's no analytics/tracking to disclose).
567710

568711
## Conventions
569712

@@ -573,3 +716,13 @@ flutter build apk --release --target-platform android-arm64 # release APK (arm
573716
- Never commit `server/data/` (holds the db and the auth token).
574717
- Both `clients/app/pubspec.lock` and `server/pubspec.lock` are tracked — keep
575718
them committed for reproducible builds (F-Droid requirement).
719+
- `server/pubspec.yaml`'s `version` is independent of the app's version — it
720+
tracks the **server binary/protocol**, not app releases, and must be bumped
721+
by hand whenever `server/` changes (a new endpoint, a `db.dart` schema/
722+
conflict-logic change, a dependency bump that changes behavior, etc.),
723+
even if that release doesn't touch the app at all. It's already wired
724+
through: `scripts/package-server.sh` names the tarball off this version,
725+
independently of `clients/app/pubspec.yaml`. Bump `_apiVersion` in
726+
`server/lib/api.dart` and `clients/app/lib/sync/sync_api.dart` too, in
727+
lockstep, whenever the wire protocol itself changes (not just the server's
728+
internals) — that's what actually drives `VersionMismatchException`.

‎clients/app/linux/runner/main.cc‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,17 @@
11
#include "my_application.h"
22

3+
#include <stdio.h>
4+
#include <unistd.h>
5+
36
int main(int argc, char** argv) {
47
g_autoptr(MyApplication) app = my_application_new();
5-
return g_application_run(G_APPLICATION(app), argc, argv);
8+
int exit_code = g_application_run(G_APPLICATION(app), argc, argv);
9+
10+
// By this point the GTK window is closed and the Flutter engine has
11+
// already shut down cleanly, so there's nothing left to flush or tear
12+
// down. Bypass atexit handlers via _exit() instead of returning normally:
13+
// on some NVIDIA driver versions, libEGL_nvidia registers an atexit EGL
14+
// teardown that segfaults inside libnvidia-eglcore during normal exit().
15+
fflush(nullptr);
16+
_exit(exit_code);
617
}

0 commit comments

Comments
 (0)