vimamsa 0.1.26 → 0.1.27
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/workflows/appimage.yml +93 -0
- data/.gitignore +4 -1
- data/Dockerfile +7 -4
- data/README.md +62 -16
- data/custom_example.rb +43 -13
- data/doc/TODO.md +461 -0
- data/doc/bundling_plan.md +569 -0
- data/doc/key_bindings_report_plan.md +168 -0
- data/doc/missing_vim_bindings.md +71 -0
- data/doc/modules_settings_plan.md +433 -0
- data/doc/refactor_dedup_plan.md +117 -0
- data/doc/unused_code_plan.md +120 -0
- data/doc/vim_compatibility_plan.md +296 -0
- data/doc/vimlike_vim_conflicts.md +254 -0
- data/doc/vm_snapshots_plan.md +146 -0
- data/exe/run_tests.rb +117 -3
- data/exe/vimamsa +24 -4
- data/fonts/OFL-Oxanium.txt +93 -0
- data/fonts/Oxanium[wght].ttf +0 -0
- data/icon.png +0 -0
- data/img/demo.gif +0 -0
- data/lang/hyperplaintext.lang +6 -0
- data/lib/vimamsa/ack.rb +11 -1
- data/lib/vimamsa/actions.rb +4 -1
- data/lib/vimamsa/appimage_env.rb +35 -0
- data/lib/vimamsa/audio.rb +2 -5
- data/lib/vimamsa/bookmarks.rb +302 -0
- data/lib/vimamsa/buffer.rb +593 -82
- data/lib/vimamsa/buffer_changetext.rb +102 -42
- data/lib/vimamsa/buffer_cursor.rb +7 -0
- data/lib/vimamsa/buffer_list.rb +4 -0
- data/lib/vimamsa/buffer_manager.rb +4 -1
- data/lib/vimamsa/bundled_fonts.rb +32 -0
- data/lib/vimamsa/clipboard.rb +3 -0
- data/lib/vimamsa/conf.rb +59 -3
- data/lib/vimamsa/constants.rb +3 -0
- data/lib/vimamsa/crash_handler.rb +149 -0
- data/lib/vimamsa/debug.rb +4 -1
- data/lib/vimamsa/desktop_install.rb +96 -0
- data/lib/vimamsa/diff_buffer.rb +39 -10
- data/lib/vimamsa/easy_jump.rb +3 -0
- data/lib/vimamsa/editor.rb +263 -57
- data/lib/vimamsa/encrypt.rb +78 -29
- data/lib/vimamsa/file_finder.rb +4 -19
- data/lib/vimamsa/file_history.rb +3 -0
- data/lib/vimamsa/file_manager.rb +30 -15
- data/lib/vimamsa/fold.rb +226 -0
- data/lib/vimamsa/gui.rb +520 -106
- data/lib/vimamsa/gui_command_line.rb +208 -0
- data/lib/vimamsa/gui_dialog.rb +94 -42
- data/lib/vimamsa/gui_file_panel.rb +356 -25
- data/lib/vimamsa/gui_form_generator.rb +59 -35
- data/lib/vimamsa/gui_func_panel.rb +67 -22
- data/lib/vimamsa/gui_image.rb +3 -0
- data/lib/vimamsa/gui_keylog_panel.rb +246 -0
- data/lib/vimamsa/gui_menu.rb +23 -11
- data/lib/vimamsa/gui_select_window.rb +19 -48
- data/lib/vimamsa/gui_settings.rb +78 -37
- data/lib/vimamsa/gui_sourceview.rb +273 -19
- data/lib/vimamsa/gui_sourceview_autocomplete.rb +319 -90
- data/lib/vimamsa/gui_text.rb +63 -2
- data/lib/vimamsa/gui_theme.rb +606 -0
- data/lib/vimamsa/hook.rb +3 -0
- data/lib/vimamsa/hyper_plain_text.rb +3 -0
- data/lib/vimamsa/key_actions.rb +112 -13
- data/lib/vimamsa/key_binding_tree.rb +242 -215
- data/lib/vimamsa/key_bindings_notepad.rb +43 -0
- data/lib/vimamsa/key_bindings_report.rb +261 -0
- data/lib/vimamsa/key_bindings_vim.rb +354 -0
- data/lib/vimamsa/key_bindings_vimlike.rb +65 -9
- data/lib/vimamsa/langservp.rb +271 -54
- data/lib/vimamsa/macro.rb +3 -0
- data/lib/vimamsa/main.rb +14 -8
- data/lib/vimamsa/rbvma.rb +26 -1
- data/lib/vimamsa/search.rb +3 -0
- data/lib/vimamsa/search_replace.rb +11 -10
- data/lib/vimamsa/string_util.rb +120 -40
- data/lib/vimamsa/terminal.rb +3 -0
- data/lib/vimamsa/test_framework.rb +28 -2
- data/lib/vimamsa/tests.rb +3 -0
- data/lib/vimamsa/text_objects.rb +353 -0
- data/lib/vimamsa/text_transforms.rb +14 -0
- data/lib/vimamsa/util.rb +46 -7
- data/lib/vimamsa/version.rb +1 -1
- data/lib/vimamsa.rb +0 -1
- data/modules/color_highlight/color_highlight.rb +118 -0
- data/modules/color_highlight/color_highlight_info.rb +3 -0
- data/modules/dictation/dictation.rb +1054 -0
- data/modules/dictation/dictation_info.rb +3 -0
- data/modules/dictation/whisper_worker.py +273 -0
- data/modules/ollama/ollama.rb +107 -0
- data/modules/ollama/ollama_info.rb +3 -0
- data/modules/tts/tts.rb +119 -0
- data/modules/tts/tts_info.rb +3 -0
- data/run_e2e_vm.sh +28 -0
- data/run_tests_vm.sh +130 -0
- data/scripts/appimage/AppRun +54 -0
- data/scripts/appimage/Dockerfile +18 -0
- data/scripts/appimage/build.sh +19 -0
- data/scripts/appimage/build_in_container.sh +192 -0
- data/scripts/appimage/smoke_test.sh +27 -0
- data/scripts/demo/demo_steps.txt +59 -0
- data/scripts/demo/record_demo.rb +177 -0
- data/scripts/demo/shapes.rb +28 -0
- data/styles/134272-molokai.xml +3 -0
- data/styles/molokai_cyber.xml +48 -0
- data/styles/molokai_edit.xml +1 -0
- data/tests/support/virtual_keyboard.rb +254 -0
- data/tests/support/virtual_mic.rb +67 -0
- data/tests/test_ack.rb +22 -0
- data/tests/test_auto_format.rb +122 -0
- data/tests/test_autocomplete.rb +211 -0
- data/tests/test_autosave.rb +145 -0
- data/tests/test_basic_editing.rb +33 -3
- data/tests/test_bookmarks.rb +206 -0
- data/tests/test_bracket_match.rb +85 -0
- data/tests/test_bundling.rb +92 -0
- data/tests/test_color_highlight.rb +92 -0
- data/tests/test_command_line.rb +79 -0
- data/tests/test_command_line_file.rb +27 -0
- data/tests/test_context_menu_file.rb +129 -0
- data/tests/test_copy_paste.rb +80 -0
- data/tests/test_crash_handler.rb +39 -0
- data/tests/test_custom_two_phase.rb +92 -0
- data/tests/test_dialog_callback_errors.rb +44 -0
- data/tests/test_dictation.rb +294 -0
- data/tests/test_diff_buffer_name.rb +51 -0
- data/tests/test_double_click.rb +41 -0
- data/tests/test_drag_selection.rb +125 -0
- data/tests/test_e2e_cmdline.rb +116 -0
- data/tests/test_e2e_dictation.rb +98 -0
- data/tests/test_e2e_replace_char.rb +58 -0
- data/tests/test_extract_file_links.rb +55 -0
- data/tests/test_file_format.rb +217 -0
- data/tests/test_file_manager.rb +72 -0
- data/tests/test_file_panel.rb +269 -0
- data/tests/test_flash.rb +78 -0
- data/tests/test_fold.rb +111 -0
- data/tests/test_font_refresh.rb +56 -0
- data/tests/test_func_panel.rb +68 -0
- data/tests/test_grep_apply.rb +46 -0
- data/tests/test_gtk_sync.rb +126 -0
- data/tests/test_hpt_highlight_visible.rb +75 -0
- data/tests/test_hpt_link_highlight.rb +82 -0
- data/tests/test_jump_to_file.rb +41 -0
- data/tests/test_key_bindings.rb +208 -0
- data/tests/test_keylog_panel.rb +101 -0
- data/tests/test_lsp_clangd.rb +281 -0
- data/tests/test_lsp_jump.rb +87 -0
- data/tests/test_lsp_position_encoding.rb +49 -0
- data/tests/test_lsp_symbols.rb +68 -0
- data/tests/test_macro.rb +137 -0
- data/tests/test_markdown_highlight.rb +57 -0
- data/tests/test_mode_badge.rb +41 -0
- data/tests/test_notepad_bindings.rb +67 -0
- data/tests/test_popup_queue.rb +51 -0
- data/tests/test_random_edit.rb +109 -0
- data/tests/test_revert.rb +127 -0
- data/tests/test_startup_file.rb +58 -0
- data/tests/test_status_area.rb +50 -0
- data/tests/test_text_objects.rb +163 -0
- data/tests/test_text_transforms.rb +329 -0
- data/tests/test_tts.rb +68 -0
- data/tests/test_vim_bindings.rb +252 -0
- data/tests/test_vim_conflicts.rb +63 -0
- data/tests/test_window_layout.rb +219 -0
- data/vimamsa.gemspec +3 -1
- data/vm_guest_run.sh +109 -0
- metadata +112 -10
|
@@ -0,0 +1,569 @@
|
|
|
1
|
+
# Plan: Vimamsa as a single downloadable app
|
|
2
|
+
|
|
3
|
+
## Goal
|
|
4
|
+
|
|
5
|
+
A user downloads one file and runs it. They don't need to install Ruby, compile gems
|
|
6
|
+
or install `-dev` packages. Today, installing means: a system Ruby 3.x, about 15 GTK
|
|
7
|
+
`-dev` packages, `gem build` + `gem install`, which compiles the vmaext C extension and
|
|
8
|
+
all the Ruby-GNOME native extensions (`install.sh`, `Dockerfile`, `vm_guest_run.sh`).
|
|
9
|
+
That takes several minutes and fails easily on unusual systems.
|
|
10
|
+
|
|
11
|
+
This document replaces earlier informal AppImage notes with a checked, concrete plan.
|
|
12
|
+
|
|
13
|
+
## What has to be bundled (verified 2026-11-19)
|
|
14
|
+
|
|
15
|
+
| Layer | Contents | Notes |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| Ruby runtime | Ruby 3.x interpreter + stdlib (dev: 3.4.9) | must be relocatable |
|
|
18
|
+
| Pure-Ruby gems | ripl, ripl-multi_line, differ, parallel, listen, language_server-protocol, rufo, ruby-lsp (+ prism, rbs, sorbet-runtime…) | `ruby-lsp` and `rufo` are runtime deps in the gemspec. Both stay in the bundle (see code change 5). |
|
|
19
|
+
| Native gems | glib2, gobject-introspection, gio2, cairo, cairo-gobject, pango, gdk_pixbuf2, gdk4, gtk4, gtksourceview5, gstreamer, vte4, ffi, rb-inotify (via listen), StrIdx | compiled against the build machine's libs |
|
|
20
|
+
| Own C extension | `ext/vmaext` (`vmaext.so`) | built by `extconf.rb` |
|
|
21
|
+
| **GI typelibs** | `Gtk-4.0`, `Gdk-4.0`, `Gsk-4.0`, `GtkSource-5`, `Gst-1.0`, `GstBase-1.0`, `Vte-3.91`, `Pango-1.0`, `PangoCairo`, `GLib/GObject/Gio-2.0`, `GdkPixbuf-2.0`, `Graphene-1.0`, `HarfBuzz-0.0`, `cairo-1.0`, `freetype2-2.0`, `GModule-2.0` … | **The main gotcha.** Ruby-GNOME loads most of the API at runtime through GObject Introspection (`/usr/lib/x86_64-linux-gnu/girepository-1.0/*.typelib`). The libraries the typelibs point to are `dlopen`ed, so `ldd`-based tools don't see them. |
|
|
22
|
+
| Shared libs | GTK4, GtkSourceView 5, VTE (gtk4), GStreamer core + base/good plugins, pango, cairo, harfbuzz, glib, libgirepository, graphene, gdk-pixbuf + loaders | leave out glibc, libGL/GPU drivers, fontconfig config (the standard AppImage excludelist) |
|
|
23
|
+
| Runtime data | `share/gtksourceview-5/` (language-specs incl. `def.lang`, `markdown.lang`; styles), GSettings schemas (compiled), gdk-pixbuf `loaders.cache`, Adwaita icon theme (symbolic icons; `gui.rb:619` forces the Adwaita theme), GStreamer `gst-plugin-scanner` | |
|
|
24
|
+
| App files | `lib/`, `exe/`, `ext/`, `lang/`, `styles/`, `fonts/`, `modules/`, `icon.png`, `custom_example.rb`, `demo.txt`, README.md | `ppath()` (`util.rb:357`) resolves `lib/vimamsa/../../<x>`, so the repo layout must stay intact |
|
|
25
|
+
|
|
26
|
+
**Not bundled; stays a host requirement or a module requirement:** ack, clang-format,
|
|
27
|
+
git, diff, gnome-terminal (`terminal.rb:22`), xdg-open, ollama, piper/aplay, and the
|
|
28
|
+
dictation Python worker (faster-whisper + CUDA is far too large). That matches
|
|
29
|
+
`doc/modules_settings_plan.md`: the modules page tells the user what to install.
|
|
30
|
+
|
|
31
|
+
## Options
|
|
32
|
+
|
|
33
|
+
### A. AppImage (recommended for "one downloadable file")
|
|
34
|
+
|
|
35
|
+
One executable file (`Vimamsa-x86_64.AppImage`): download, `chmod +x`, run. No sandbox,
|
|
36
|
+
so the many external tools the editor runs (ack, git, clang-format, gnome-terminal,
|
|
37
|
+
`bash -c`) work exactly as they do today. That decides it for a text editor.
|
|
38
|
+
|
|
39
|
+
Build steps (a script, `scripts/build_appimage.sh`, run inside a container):
|
|
40
|
+
1. **Build host**: Ubuntu 22.04 (glibc 2.35, GTK 4.6, GtkSourceView 5.4, VTE 0.68)
|
|
41
|
+
gives the widest compatibility, but it's far behind the development GTK. Ubuntu
|
|
42
|
+
24.04 (GTK 4.14) matches development. See "GTK version differences" below for
|
|
43
|
+
the trade-off. Decide after running the test suite on 22.04.
|
|
44
|
+
2. **Ruby**: build from source with `--prefix=/usr --enable-load-relative
|
|
45
|
+
--enable-shared`, `make install DESTDIR=AppDir`. `load-relative` makes the
|
|
46
|
+
interpreter find its stdlib relative to the binary. (traveling-ruby isn't
|
|
47
|
+
reliably maintained; ruby-build + load-relative is simpler to control.)
|
|
48
|
+
3. **Gems**: `AppDir/usr/bin/ruby -S gem install --no-document --install-dir AppDir/usr/lib/ruby/gems/3.x.0 vimamsa-*.gem`
|
|
49
|
+
(or `bundle install --deployment` from a Gemfile.lock to pin versions). This
|
|
50
|
+
compiles the native gems and vmaext against the build host's libs.
|
|
51
|
+
4. **Libraries**: `linuxdeploy --appdir AppDir --plugin gtk --plugin gstreamer`
|
|
52
|
+
deploys the dependencies of every `.so` under AppDir (point it at the gem
|
|
53
|
+
extension `.so`s with `--library` / `--deploy-deps-only`). GTK4 support in
|
|
54
|
+
linuxdeploy-plugin-gtk is newer than its GTK3 support and may need patching.
|
|
55
|
+
Then **explicitly** add the libs that are only reached through typelibs:
|
|
56
|
+
libgtk-4, libgtksourceview-5, libvte-2.91-gtk4, libgstreamer-1.0, libgraphene,
|
|
57
|
+
libgirepository-1.0, and check with `GI_TYPELIB_PATH` + `LD_DEBUG=libs` that
|
|
58
|
+
nothing is loaded from the host.
|
|
59
|
+
5. **Typelibs and data**: copy the typelibs listed above to
|
|
60
|
+
`AppDir/usr/lib/girepository-1.0/`, copy `share/gtksourceview-5`, the Adwaita
|
|
61
|
+
icons and the schemas, and run `glib-compile-schemas`.
|
|
62
|
+
6. **AppRun**: a shell script that exports
|
|
63
|
+
`GI_TYPELIB_PATH=$APPDIR/usr/lib/girepository-1.0`,
|
|
64
|
+
`XDG_DATA_DIRS=$APPDIR/usr/share:${XDG_DATA_DIRS:-/usr/local/share:/usr/share}`,
|
|
65
|
+
`GSETTINGS_SCHEMA_DIR`, `GDK_PIXBUF_MODULE_FILE`, `GST_PLUGIN_SYSTEM_PATH`,
|
|
66
|
+
`GST_PLUGIN_SCANNER`, `GEM_HOME`/`GEM_PATH` (bundled only; unset the user's
|
|
67
|
+
`GEM_HOME` and `RUBYOPT`), and `LD_LIBRARY_PATH` if linuxdeploy didn't set an
|
|
68
|
+
rpath, then runs `exec "$APPDIR/usr/bin/ruby" "$APPDIR/usr/share/vimamsa/exe/vimamsa" "$@"`.
|
|
69
|
+
7. **Pack**: `appimagetool` with the **new static type-2 runtime**. The old runtime
|
|
70
|
+
needs `libfuse2`, which Ubuntu 24.04 no longer installs by default; with the old
|
|
71
|
+
runtime users would need `sudo apt install libfuse2t64` or
|
|
72
|
+
`--appimage-extract-and-run`. Embed update info (zsync) for AppImageUpdate.
|
|
73
|
+
8. **CI**: a GitHub Actions job in a container of the build host (proposed `ubuntu:24.04`) builds it on a tag and
|
|
74
|
+
attaches it to the GitHub release.
|
|
75
|
+
|
|
76
|
+
Expected size: Ruby + gems about 60–80 MB, GTK4 + deps about 60 MB, GStreamer
|
|
77
|
+
base/good about 30–60 MB. Roughly **150–250 MB uncompressed and 60–100 MB as an
|
|
78
|
+
AppImage** (squashfs/zstd). Trimming GStreamer to the plugins audio playback and
|
|
79
|
+
dictation capture need (`playbin`, `autoaudiosrc`, decodebin, mp3/ogg/wav) keeps it at
|
|
80
|
+
the low end.
|
|
81
|
+
|
|
82
|
+
#### The typelib problem is build-time only
|
|
83
|
+
|
|
84
|
+
The hardest part of the AppImage (step 4: finding every library and data file that
|
|
85
|
+
Ruby-GNOME loads at runtime through GObject Introspection) is a problem for **whoever
|
|
86
|
+
builds the AppImage**, not for users. `ldd`-based tools can't see those libraries, so
|
|
87
|
+
the build script has to list them by hand. If one is missed, the AppImage still works
|
|
88
|
+
on the build machine and the developer's desktop, because the library is there in
|
|
89
|
+
`/usr/lib`. It then fails on a user's machine that doesn't have it, with an error such
|
|
90
|
+
as `Typelib file for namespace 'GtkSource' not found`. That's why the clean-machine
|
|
91
|
+
test below is required. Once the list is complete, users see none of this.
|
|
92
|
+
|
|
93
|
+
#### What users of the AppImage have to do
|
|
94
|
+
|
|
95
|
+
Required:
|
|
96
|
+
1. Download `Vimamsa-x86_64.AppImage`.
|
|
97
|
+
2. Make it executable: `chmod +x Vimamsa-x86_64.AppImage`, or Properties ▸
|
|
98
|
+
"Allow executing file as program" in the file manager.
|
|
99
|
+
3. Run it, by double-click or `./Vimamsa-x86_64.AppImage [file]`.
|
|
100
|
+
|
|
101
|
+
No Ruby, no gems, no `apt install`, no compiling. On first start the editor installs
|
|
102
|
+
its own launcher and icon into `~/.local/share` (`desktop_install.rb`), pointing at
|
|
103
|
+
the AppImage (code change 3), so after that it appears in the app menu. If the user
|
|
104
|
+
moves the file, the next start updates the launcher.
|
|
105
|
+
|
|
106
|
+
Only in special cases:
|
|
107
|
+
- **libfuse2**: not needed with the static type-2 runtime (step 7). If an older
|
|
108
|
+
runtime were used, Ubuntu 22.04+ users would need `sudo apt install libfuse2` /
|
|
109
|
+
`libfuse2t64`, or would have to run it with `--appimage-extract-and-run`. Using the
|
|
110
|
+
static runtime avoids this, and it's a build decision, not a user action.
|
|
111
|
+
- **System requirements**: x86_64 Linux with glibc at least the build host's: with
|
|
112
|
+
the proposed Ubuntu 24.04 build host, glibc ≥ 2.39 (Ubuntu 24.04, Debian 13, Fedora 40
|
|
113
|
+
or newer; 22.04 would allow glibc ≥ 2.35) and a Wayland or X11 desktop. Older distros or arm64 need a
|
|
114
|
+
separate build. The GPU driver and fonts come from the host, as with any
|
|
115
|
+
AppImage.
|
|
116
|
+
- **Restricted `/tmp` or home on `noexec`** (some corporate setups): AppImages can't
|
|
117
|
+
run from a `noexec` mount, so the user moves the file to e.g. `~/Applications`.
|
|
118
|
+
|
|
119
|
+
Optional, only for the features that use external programs (same as today, and the
|
|
120
|
+
modules page in `doc/modules_settings_plan.md` lists them with copyable commands):
|
|
121
|
+
|
|
122
|
+
| Feature | User action |
|
|
123
|
+
|---|---|
|
|
124
|
+
| Content search (ack) | `sudo apt install ack` |
|
|
125
|
+
| Auto-format C/C++/JS | `sudo apt install clang-format` (Ruby works out of the box: rufo is bundled) |
|
|
126
|
+
| Git diff | `git` (usually already installed) |
|
|
127
|
+
| Run line in terminal | `gnome-terminal` (until `cnf.terminal.command` exists) |
|
|
128
|
+
| LSP | Ruby: works out of the box with the bundled `ruby-lsp`. C/C++: `sudo apt install clangd` |
|
|
129
|
+
| Ollama, TTS, dictation modules | see each module's card (Ollama install + model; piper + voice; faster-whisper venv + ffmpeg) |
|
|
130
|
+
|
|
131
|
+
Everything else works without further steps: editing, highlighting, the file
|
|
132
|
+
panel, image display, audio playback (bundled GStreamer plugins) and the embedded
|
|
133
|
+
terminal (bundled VTE).
|
|
134
|
+
|
|
135
|
+
Updates: download the new AppImage, or use AppImageUpdate / a tool like Gear Lever,
|
|
136
|
+
which read the embedded zsync update info. An in-editor "new version available"
|
|
137
|
+
notice could come later.
|
|
138
|
+
|
|
139
|
+
### B. Flatpak (good second step, for Flathub)
|
|
140
|
+
|
|
141
|
+
- **Runtime**: `org.gnome.Platform` (current release) already contains GTK4,
|
|
142
|
+
GtkSourceView 5, GStreamer and the typelibs. Check whether VTE (gtk4) is in the
|
|
143
|
+
runtime; if not, add it as a manifest module.
|
|
144
|
+
- **Ruby** isn't in the GNOME SDK, so build it as a module. Gems become generated
|
|
145
|
+
`sources` (flatpak-builder-tools has a RubyGems generator), since Flathub builds
|
|
146
|
+
run offline.
|
|
147
|
+
- Can also be shipped as one file (`flatpak build-bundle` → `vimamsa.flatpak`), but
|
|
148
|
+
the user needs Flatpak installed.
|
|
149
|
+
- **The problem for an editor is the sandbox.**
|
|
150
|
+
- It needs `--filesystem=host` to edit arbitrary files.
|
|
151
|
+
- Every external command (ack, git, clang-format, gnome-terminal, `bash -c` in
|
|
152
|
+
auto_format, `command_to_buf`, LSP servers like clangd/solargraph, ollama,
|
|
153
|
+
piper) would run *inside* the sandbox, where those tools don't exist.
|
|
154
|
+
- The fix is a `host_cmd` wrapper that prefixes `flatpak-spawn --host` when
|
|
155
|
+
`/.flatpak-info` exists, plus `--talk-name=org.freedesktop.Flatpak`. Flathub
|
|
156
|
+
reviewers accept that for IDEs, but every `system` / `IO.popen` / backtick call
|
|
157
|
+
site has to go through the wrapper.
|
|
158
|
+
- Upside: desktop integration and updates come free, and the size is small
|
|
159
|
+
(shared runtime).
|
|
160
|
+
|
|
161
|
+
### C. Not recommended
|
|
162
|
+
|
|
163
|
+
- **Tebako / ruby-packer** (Ruby + gems in one executable): GTK4, the typelibs and
|
|
164
|
+
GStreamer still have to be on the host, so the user still runs `apt install`. That
|
|
165
|
+
only half solves the problem.
|
|
166
|
+
- **Snap**: similar sandbox problems to Flatpak (classic confinement needs a manual
|
|
167
|
+
review), and Ubuntu-centric.
|
|
168
|
+
- **Docker**: not a desktop app.
|
|
169
|
+
|
|
170
|
+
## GTK version differences
|
|
171
|
+
|
|
172
|
+
The AppImage carries its own GTK, so users always run the **build host's** GTK version,
|
|
173
|
+
whatever their distro has. Development currently runs on **GTK 4.14.5 /
|
|
174
|
+
GtkSourceView 5.12** (Ubuntu 24.04). Ubuntu 22.04 would bundle **GTK 4.6 /
|
|
175
|
+
GtkSourceView 5.4**: two years and eight minor versions older. Problems, from most to
|
|
176
|
+
least likely:
|
|
177
|
+
|
|
178
|
+
1. **Behavior differs from what was developed and tested.**
|
|
179
|
+
- API: a scan (2026-11-19) found none of the 4.10+ classes (`Gtk::FileDialog`,
|
|
180
|
+
`AlertDialog`, `ColorDialog`, `UriLauncher`, …). The code uses the older
|
|
181
|
+
`Gtk::FileChooserDialog` (`gui.rb`, `buffer.rb`, `gui_settings.rb`), so it
|
|
182
|
+
should *load* on 4.6.
|
|
183
|
+
- But many bugs were fixed between 4.6 and 4.14: popovers, clipboard (the editor
|
|
184
|
+
already has a workaround for ruby-gnome#1609), TextView child anchors (used by
|
|
185
|
+
the calculator, terminal and images), and focus/key handling. The editor
|
|
186
|
+
depends heavily on key-event details.
|
|
187
|
+
- The only reliable check is to **run the full test suite against the bundled
|
|
188
|
+
libraries**, not the host's. That means running `exe/run_tests.rb` with the
|
|
189
|
+
AppDir's Ruby and `GI_TYPELIB_PATH`/`LD_LIBRARY_PATH`, or inside the AppImage,
|
|
190
|
+
on a clean VM.
|
|
191
|
+
2. **Visual and rendering differences.**
|
|
192
|
+
- Fractional scaling (`wp_fractional_scale`) arrived in GTK 4.12. With 4.6,
|
|
193
|
+
users on 125%/150% Wayland scaling get **blurry text**. For a text editor
|
|
194
|
+
that's the most user-visible risk.
|
|
195
|
+
- The renderers changed too (new GL/Vulkan renderers in 4.14), and so did font
|
|
196
|
+
rendering (hinting and subpixel positioning in 4.16).
|
|
197
|
+
- The built-in Adwaita theme (`gui.rb:619` forces it) looks different in each
|
|
198
|
+
version.
|
|
199
|
+
- CSS: `gui_theme.rb` and others load custom CSS. GTK 4.16 deprecated
|
|
200
|
+
`@define-color` / named colors in favor of CSS variables. CSS written and
|
|
201
|
+
tested on one version may render differently or warn on another. Keep the CSS
|
|
202
|
+
to features that 4.6 supports and that 4.16+ hasn't deprecated, or check the
|
|
203
|
+
version.
|
|
204
|
+
3. **GtkSourceView 5.4 vs 5.12.**
|
|
205
|
+
- The markdown/markup styles (`def:heading`, `def:inline-code`, …, see the
|
|
206
|
+
markdown item in `doc/TODO.md`) may differ or be missing in 5.4's `def.lang`
|
|
207
|
+
/ `markdown.lang`. Check before writing the overlay fix against 5.12.
|
|
208
|
+
- The style schemes in `styles/` and the generated overlay use features of the
|
|
209
|
+
`.xml` format. Check them on 5.4.
|
|
210
|
+
- `XDG_DATA_DIRS` ends with the host's `/usr/share`. If a language-spec is
|
|
211
|
+
missing from the bundle, the bundled (older) GtkSourceView can pick up the
|
|
212
|
+
host's (newer) `.lang` file, which may use features it doesn't support. Bundle
|
|
213
|
+
the complete `share/gtksourceview-5` so the bundled copies win.
|
|
214
|
+
4. **Mixing the bundled GTK with modules from the host.**
|
|
215
|
+
- GTK loads plug-in modules from the host: input methods (IBus/Fcitx), GIO
|
|
216
|
+
modules (gvfs for trash and remote locations in the file chooser), the dconf
|
|
217
|
+
settings backend, and print backends. Modules built for the host's newer GTK
|
|
218
|
+
can fail to load or **crash** the bundled older GTK.
|
|
219
|
+
- The usual AppImage answer is to isolate them (`GTK_PATH`/`GIO_MODULE_DIR`
|
|
220
|
+
pointing into the AppDir). But then users of IBus/Fcitx (CJK input) lose their
|
|
221
|
+
input method, and get only GTK's built-in compose/dead-key handling. The editor
|
|
222
|
+
relies on input-method commits for AltGr/dead keys (`gui_sourceview.rb`), so
|
|
223
|
+
test this with a non-US keyboard layout.
|
|
224
|
+
- Decide: bundle the gvfs/ibus GTK4 modules from the build host (matching
|
|
225
|
+
version), or accept the limitation and document it.
|
|
226
|
+
5. **Typelib vs library mismatch.** If a typelib is missing from the bundle,
|
|
227
|
+
GObject Introspection falls back to the host's
|
|
228
|
+
`/usr/lib/*/girepository-1.0` typelib. That one describes a *different version*
|
|
229
|
+
of the library than the bundled `.so`, which can cause wrong calls or crashes
|
|
230
|
+
instead of a clean error. It's the same as the build-time problem above:
|
|
231
|
+
bundle the complete set, and in the test run check that no typelib is loaded
|
|
232
|
+
from the host (`GI_DEBUG`, `strace -e openat`).
|
|
233
|
+
6. **Host graphics stack.** libGL/Mesa/Vulkan come from the host (excludelist). A
|
|
234
|
+
newer host Mesa may need a newer `libstdc++`/`libdrm` than the bundled ones, the
|
|
235
|
+
classic AppImage "`GLIBCXX_3.4.xx` not found" error. Don't bundle `libstdc++` (or
|
|
236
|
+
bundle it with a version check). As a fallback, AppRun can set
|
|
237
|
+
`GSK_RENDERER=cairo` when GL initialization fails.
|
|
238
|
+
7. **Ruby-GNOME gems vs GTK version.** The gems (4.3.x) are compiled against the
|
|
239
|
+
build host's headers, so they match the bundled GTK. That's fine as long as gems,
|
|
240
|
+
typelibs and libraries all come from the same build host. Never reuse gems
|
|
241
|
+
compiled on the development machine.
|
|
242
|
+
8. **Future: deprecations.** `Gtk::FileChooserDialog` and friends are deprecated
|
|
243
|
+
since 4.10 and print warnings on newer GTK. They keep working in GTK 4, but are
|
|
244
|
+
gone in GTK 5. Not urgent, but don't start new code on deprecated APIs.
|
|
245
|
+
|
|
246
|
+
**Recommendation.** The build host trades compatibility against matching the tested
|
|
247
|
+
version:
|
|
248
|
+
|
|
249
|
+
| Build host | GTK / GSV | Runs on (glibc) | Risk |
|
|
250
|
+
|---|---|---|---|
|
|
251
|
+
| Ubuntu 22.04 | 4.6 / 5.4 | 22.04+, Debian 12, Fedora 36+ | biggest gap to development; no fractional scaling |
|
|
252
|
+
| Debian 12 | 4.8 / 5.6 | Debian 12+, Ubuntu 22.10+, Fedora 37+ | still no fractional scaling |
|
|
253
|
+
| Ubuntu 24.04 | 4.14 / 5.12 | 24.04+, Debian 13, Fedora 40+ | matches development; narrower range |
|
|
254
|
+
|
|
255
|
+
**Decided (2026-11-19): build on Ubuntu 24.04**, so the bundle runs exactly the GTK
|
|
256
|
+
the editor is developed and tested with, and fractional scaling works. Ubuntu 22.04
|
|
257
|
+
users (still supported until 2027) use `gem install` or the later Flatpak, which always
|
|
258
|
+
ships a current GNOME runtime and avoids the whole GTK-version question. Revisit if
|
|
259
|
+
22.04-era users ask for the AppImage. Add a CI job that runs the test suite against the
|
|
260
|
+
bundled libraries.
|
|
261
|
+
|
|
262
|
+
## Running on non-Ubuntu distros
|
|
263
|
+
|
|
264
|
+
An AppImage isn't tied to Ubuntu. Everything that differs between distros (Ruby, gems,
|
|
265
|
+
GTK, GtkSourceView, VTE, GStreamer, typelibs, data files) is inside the file, so all
|
|
266
|
+
distros run the same editor code on the same libraries. What still comes from the host:
|
|
267
|
+
|
|
268
|
+
| From the host | Requirement / note |
|
|
269
|
+
|---|---|
|
|
270
|
+
| **glibc** | at least the build host's: **≥ 2.39** with Ubuntu 24.04. This decides which distros work (table below). |
|
|
271
|
+
| CPU | x86_64 (an arm64 build would be separate) |
|
|
272
|
+
| Kernel | any modern one. The static type-2 runtime needs no `libfuse2`. FUSE itself is in every desktop kernel. |
|
|
273
|
+
| Graphics | host Mesa / NVIDIA driver (`libGL`, `libEGL`, Vulkan). Works on any distro; see "Host graphics stack" above. |
|
|
274
|
+
| Fonts | host fontconfig and fonts. The default `cnf.font.family = "Monospace"` (`conf.rb:170`) resolves to each distro's monospace font (DejaVu Sans Mono, Noto Sans Mono, …), so it can look slightly different. The bundled Oxanium font is unaffected. |
|
|
275
|
+
| Audio | GStreamer's bundled `pulsesink`/`pulsesrc` talk to PipeWire (pipewire-pulse) or PulseAudio, which every current desktop distro provides |
|
|
276
|
+
| Desktop integration | `.desktop` file + icon in `~/.local/share` follow the freedesktop spec, so they work in GNOME, KDE, Xfce and others. `desktop_install.rb` already skips `gtk-update-icon-cache` / `update-desktop-database` when they're missing (`which` guards at lines 73, 77). |
|
|
277
|
+
| Wayland / X11 | GTK4 runs on all common compositors (GNOME, KDE, Sway, Hyprland) and on X11 |
|
|
278
|
+
|
|
279
|
+
### Which distros it runs on (glibc ≥ 2.39)
|
|
280
|
+
|
|
281
|
+
| Distro | glibc | Runs? |
|
|
282
|
+
|---|---|---|
|
|
283
|
+
| Ubuntu 24.04+, Linux Mint 22+, Pop!_OS 24.04, elementary OS 8, KDE neon (24.04 base) | 2.39+ | ✅ |
|
|
284
|
+
| Fedora 40+ | 2.39+ | ✅ |
|
|
285
|
+
| Debian 13 (trixie) | 2.41 | ✅ |
|
|
286
|
+
| Arch, Manjaro, EndeavourOS, openSUSE Tumbleweed, Gentoo, Void (glibc) | rolling | ✅ |
|
|
287
|
+
| openSUSE Leap 16 | 2.40 | ✅ |
|
|
288
|
+
| RHEL / Alma / Rocky 10 | 2.39 | ✅ |
|
|
289
|
+
| Fedora Silverblue / Kinoite, Bazzite (immutable) | 2.39+ | ✅ (AppImages suit immutable systems well; optional tools go through toolbox / distrobox) |
|
|
290
|
+
| WSL2 + WSLg with Ubuntu 24.04 | 2.39 | ✅ (not tested) |
|
|
291
|
+
| Ubuntu 22.04, Linux Mint 21, Zorin OS 17 | 2.35 | ❌ use `gem install` / Flatpak |
|
|
292
|
+
| Debian 12 (bookworm), ChromeOS Crostini (Debian 12) | 2.36 | ❌ |
|
|
293
|
+
| openSUSE Leap 15.6 | 2.38 | ❌ |
|
|
294
|
+
| RHEL / Alma / Rocky 9 | 2.34 | ❌ |
|
|
295
|
+
| NixOS | (no FHS) | ⚠️ needs `appimage-run` (or `programs.appimage.enable = true; binfmt = true;`) |
|
|
296
|
+
| Alpine, Void-musl, Chimera (musl libc) | — | ❌ glibc-only; would need the Flatpak |
|
|
297
|
+
|
|
298
|
+
On a too-old glibc the AppImage fails right at start with
|
|
299
|
+
`/lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.39' not found`. AppRun can't catch
|
|
300
|
+
this, because the bundled Ruby itself doesn't load. Mention it in the download
|
|
301
|
+
instructions (README: "requires glibc 2.39+: Ubuntu 24.04, Fedora 40, Debian 13 or
|
|
302
|
+
newer").
|
|
303
|
+
|
|
304
|
+
### Distro-specific issues inside the editor
|
|
305
|
+
|
|
306
|
+
These aren't about the AppImage itself; they're about the external tools it calls.
|
|
307
|
+
They need fixing for non-Ubuntu users regardless of how the editor is packaged:
|
|
308
|
+
|
|
309
|
+
1. **Hardcoded `gnome-terminal`** (`terminal.rb:22`): KDE (Konsole), Xfce
|
|
310
|
+
(xfce4-terminal) and most non-GNOME setups don't have it, so "Execute line in
|
|
311
|
+
terminal" fails silently there. Fix: a `cnf.terminal.command` setting, with
|
|
312
|
+
auto-detection in order: `$TERMINAL`, `x-terminal-emulator` (Debian alternatives),
|
|
313
|
+
`gnome-terminal`, `konsole`, `xfce4-terminal`, `kitty`, `alacritty`, `foot`,
|
|
314
|
+
`wezterm`, `xterm`, each with its own "run this command" arguments. This is
|
|
315
|
+
already noted in `doc/modules_settings_plan.md` ("Keep in core").
|
|
316
|
+
2. **Install commands on the modules page are `apt`-only.** Read `ID` / `ID_LIKE`
|
|
317
|
+
from `/etc/os-release` and show the matching command. Package names also differ:
|
|
318
|
+
|
|
319
|
+
| Tool | Debian/Ubuntu | Fedora | Arch | openSUSE |
|
|
320
|
+
|---|---|---|---|---|
|
|
321
|
+
| ack | `ack` | `ack` | `ack` | `ack` |
|
|
322
|
+
| clang-format | `clang-format` | `clang-tools-extra` | `clang` | `clang-tools` |
|
|
323
|
+
| clangd | `clangd` | `clang-tools-extra` | `clang` | `clang-tools` |
|
|
324
|
+
| ffmpeg | `ffmpeg` | `ffmpeg-free` (or RPM Fusion `ffmpeg`) | `ffmpeg` | `ffmpeg` (Packman for full codecs) |
|
|
325
|
+
| aplay | `alsa-utils` | `alsa-utils` | `alsa-utils` | `alsa-utils` |
|
|
326
|
+
|
|
327
|
+
Verify these names when implementing. Fall back to the generic text
|
|
328
|
+
("install clang-format with your package manager") for unknown distros.
|
|
329
|
+
Immutable distros need `toolbox`/`distrobox` or `rpm-ostree install`; show a hint
|
|
330
|
+
when `/run/ostree-booted` exists.
|
|
331
|
+
3. **pip in a venv** (dictation, TTS) works the same on all distros. `python3 -m venv`
|
|
332
|
+
needs `python3-venv` on Debian/Ubuntu only; other distros include it.
|
|
333
|
+
|
|
334
|
+
### Testing on other distros
|
|
335
|
+
|
|
336
|
+
- **CI smoke test matrix** in containers: `fedora:40`, `debian:trixie`, `archlinux`,
|
|
337
|
+
`opensuse/tumbleweed`, `ubuntu:24.04`. Install only `xvfb` (and Mesa for software
|
|
338
|
+
GL), then run `xvfb-run ./Vimamsa-x86_64.AppImage --appimage-extract-and-run --test <smoke test>`.
|
|
339
|
+
Containers have no FUSE, hence `--appimage-extract-and-run`. Also add a
|
|
340
|
+
`debian:bookworm` job that is *expected* to fail with the glibc error, so the
|
|
341
|
+
minimum stays documented and tested.
|
|
342
|
+
- **By hand, once per release** on a real desktop: Fedora (GNOME, SELinux on), KDE
|
|
343
|
+
(Kubuntu or Fedora KDE) for non-GNOME desktop integration, input methods and
|
|
344
|
+
terminal detection, and Arch. A live USB or another VirtualBox VM next to the test VM
|
|
345
|
+
is enough.
|
|
346
|
+
|
|
347
|
+
## Alternative: a newer GTK (Ubuntu 26.04's) in the bundle
|
|
348
|
+
|
|
349
|
+
Checked 2026-11-19 in an `ubuntu:26.04` container on the development machine (Ubuntu
|
|
350
|
+
24.04.5, glibc 2.39, GTK 4.14.5):
|
|
351
|
+
|
|
352
|
+
| | Ubuntu 24.04 (dev machine) | Ubuntu 26.04 |
|
|
353
|
+
|---|---|---|
|
|
354
|
+
| glibc | 2.39 | **2.43** |
|
|
355
|
+
| GTK | 4.14.5 | 4.22.4 |
|
|
356
|
+
| GtkSourceView | 5.12 | 5.18.0 |
|
|
357
|
+
| VTE (gtk4) | 0.76.0 | 0.84.0 |
|
|
358
|
+
| GLib | 2.80 | 2.88.0 |
|
|
359
|
+
| GStreamer | 1.24 | 1.28.2 |
|
|
360
|
+
| libgirepository-1.0 | yes | still shipped (1.86); 2.0 is in GLib 2.88 |
|
|
361
|
+
|
|
362
|
+
Both of the following can be done on the development machine with Docker (it's
|
|
363
|
+
installed), but they're very different.
|
|
364
|
+
|
|
365
|
+
**A. Build inside an `ubuntu:26.04` container.** Technically trivial: the same
|
|
366
|
+
build script with a different base image. But the AppImage then needs **glibc ≥ 2.43**.
|
|
367
|
+
It would *not* run on Ubuntu 24.04, the current LTS (including the development
|
|
368
|
+
machine itself), Debian 13 (2.41) or Fedora 43 (2.42). Only Ubuntu 26.04+, Fedora 44+
|
|
369
|
+
and the rolling distros could run it. **Not recommended** until 26.04-era distros are
|
|
370
|
+
the norm (about 2028).
|
|
371
|
+
|
|
372
|
+
**B. Build GTK 4.22 from source on top of the 24.04 base** (in a 24.04 container):
|
|
373
|
+
glibc stays 2.39 and compatibility stays the same, but the bundle gets the newer GTK
|
|
374
|
+
stack.
|
|
375
|
+
- Build into a prefix (e.g. `/opt/vma-gtk`) with meson, roughly in dependency order:
|
|
376
|
+
- GLib 2.88 (+ girepository)
|
|
377
|
+
- gobject-introspection 1.86
|
|
378
|
+
- wayland-protocols
|
|
379
|
+
- harfbuzz / pango / graphene / libepoxy as GTK 4.22 requires (check the minimum
|
|
380
|
+
versions in its `meson.build`; 24.04's may be too old)
|
|
381
|
+
- GTK 4.22
|
|
382
|
+
- GtkSourceView 5.18
|
|
383
|
+
- VTE 0.84 (C++20, gnutls, pcre2)
|
|
384
|
+
|
|
385
|
+
GStreamer can stay at 24.04's 1.24.
|
|
386
|
+
- Then compile Ruby and the Ruby-GNOME gems against that prefix
|
|
387
|
+
(`PKG_CONFIG_PATH=/opt/vma-gtk/lib/pkgconfig`), and point linuxdeploy at it.
|
|
388
|
+
- Use an existing build recipe rather than writing one: gnome-build-meta /
|
|
389
|
+
BuildStream, or a jhbuild moduleset.
|
|
390
|
+
- Effort: **about 2–4 extra days**, plus ongoing upkeep (rebuild for security
|
|
391
|
+
fixes, follow GTK's dependency bumps).
|
|
392
|
+
- Disk: about 10–15 GB for the build container. Check free space on the build
|
|
393
|
+
machine first.
|
|
394
|
+
- Risks:
|
|
395
|
+
- The bundled GLib (2.88) is newer than the host's on 24.04. Host GIO/GTK
|
|
396
|
+
modules (gvfs, dconf, IBus) are built against the older GLib/GTK. The bundle
|
|
397
|
+
isolates them anyway (see "GTK version differences" point 4), but it's one more
|
|
398
|
+
thing to test.
|
|
399
|
+
- Ruby-GNOME 4.3.x must work with GLib 2.88. GLib 2.80+ moved GIRepository
|
|
400
|
+
into GLib (`girepository-2.0`). Check which one the gem links, and use a recent
|
|
401
|
+
Ruby-GNOME release.
|
|
402
|
+
|
|
403
|
+
**Either way the test-coverage argument from "GTK version differences" applies in
|
|
404
|
+
reverse**: the editor is developed and tested on GTK 4.14, so a 4.22 bundle runs a GTK
|
|
405
|
+
nobody has tested it on. It's newer and has fewer bugs, but there are real behavior
|
|
406
|
+
changes:
|
|
407
|
+
- CSS: named colors are deprecated since 4.16
|
|
408
|
+
- new renderers and font rendering
|
|
409
|
+
- `FileChooserDialog` deprecation warnings
|
|
410
|
+
- GtkSourceView style changes
|
|
411
|
+
|
|
412
|
+
So the full test suite would have to run against the bundled 4.22 libraries in CI, and
|
|
413
|
+
ideally the development machine would move to the same GTK.
|
|
414
|
+
|
|
415
|
+
**Worth it?** GTK 4.14 already has fractional scaling, so 4.22 mainly brings
|
|
416
|
+
rendering and font polish, bug fixes, and GtkSourceView 5.18.
|
|
417
|
+
|
|
418
|
+
**Decided (2026-11-19): stay with the plain Ubuntu 24.04 build (system GTK 4.14) for
|
|
419
|
+
now.** Neither A nor B is planned. Reconsider only if a specific GTK bug or feature
|
|
420
|
+
needs a newer GTK; then use option B in a container, not option A. Look at it again
|
|
421
|
+
when the development machine moves to Ubuntu 26.04.
|
|
422
|
+
|
|
423
|
+
## Code changes needed regardless of format
|
|
424
|
+
|
|
425
|
+
1. **`exe/vimamsa` puts paths relative to the *current directory* on `$LOAD_PATH`:**
|
|
426
|
+
`$LOAD_PATH.unshift(File.expand_path("lib"))` and the same for `"ext"` (lines 44-45).
|
|
427
|
+
`scriptdir` is computed at line 9 and never used. From an AppImage, or when
|
|
428
|
+
started from another directory, it would pick up a random `./lib` from wherever
|
|
429
|
+
the user is. Use `File.join(scriptdir, "lib")`. This also affects running from
|
|
430
|
+
source.
|
|
431
|
+
2. `lib/vimamsa.rb` adds `ext/stridx` to the load path, but that directory no longer
|
|
432
|
+
exists. StrIdx now comes from the gem. Remove the dead line.
|
|
433
|
+
3. **`desktop_install.rb`** writes `Exec=vimamsa %F` (line 64), which only works when
|
|
434
|
+
the gem's binstub is on PATH. When `ENV["APPIMAGE"]` is set, write
|
|
435
|
+
`Exec="<$APPIMAGE>" %F` and refresh it if the AppImage has moved. (The
|
|
436
|
+
install-only-when-changed logic is already there.) Flatpak installs its own
|
|
437
|
+
desktop file, so skip this there.
|
|
438
|
+
4. **Read-only app directory**: an AppImage is mounted read-only. Checked: nothing
|
|
439
|
+
writes through `ppath()` (generated styles go to `~/.config/vimamsa/styles`), so
|
|
440
|
+
this is OK today. Add a test or a review rule to keep it that way. This ties in
|
|
441
|
+
with the XDG item in `doc/TODO.md`.
|
|
442
|
+
5. **Runtime deps: keep `ruby-lsp` in the bundle for now** (decided 2026-11-19).
|
|
443
|
+
It pulls in prism, rbs and sorbet-runtime (tens of MB), which is accepted. For it
|
|
444
|
+
to be usable from the bundle:
|
|
445
|
+
- AppRun puts `$APPDIR/usr/bin` on `PATH` and a `ruby-lsp` binstub there that
|
|
446
|
+
uses the bundled Ruby, so a `cnf.lsp.server` command of `ruby-lsp` (not
|
|
447
|
+
`bundle exec ruby-lsp` as in `custom_example.rb:94`) finds it. A built-in
|
|
448
|
+
default server preset could point at it directly (see the LSP presets in
|
|
449
|
+
`doc/modules_settings_plan.md`).
|
|
450
|
+
- Caveat: in a project with a Gemfile, ruby-lsp builds a "composed bundle" using
|
|
451
|
+
the *bundled* Ruby. If the project needs a different Ruby version, this can
|
|
452
|
+
fail, and then the user's own `ruby-lsp` (configured in `cnf.lsp.server`)
|
|
453
|
+
should be used instead. Mention this on the LSP module card.
|
|
454
|
+
- Revisit trimming it if the AppImage size becomes a problem.
|
|
455
|
+
Keep `rufo` too (small; makes Ruby auto-format work out of the box).
|
|
456
|
+
6. **Version check at startup**: the bundled GTK is the build host's version. Guard
|
|
457
|
+
any newer GTK/GtkSourceView API use with `Gtk.check_version` (or keep the build
|
|
458
|
+
host's GTK as the CI baseline so it's caught).
|
|
459
|
+
7. **Ruby version**: development is on 3.4. The gemspec doesn't say a version, so
|
|
460
|
+
add `required_ruby_version`. CLAUDE.md says 3.0+, but the Dockerfile uses 3.1.
|
|
461
|
+
|
|
462
|
+
## Testing the bundle
|
|
463
|
+
|
|
464
|
+
- Smoke test in CI: `xvfb-run ./Vimamsa-x86_64.AppImage --version` (add the flag if
|
|
465
|
+
it's missing), then start it, open a file and quit, using a `--test` run of one
|
|
466
|
+
small built-in test file. Ship `tests/` inside the AppDir, or point `--test` at
|
|
467
|
+
the checkout.
|
|
468
|
+
- Run it on a **clean** machine with no Ruby or GTK dev packages:
|
|
469
|
+
- the test VM (`$VM_NAME`), restored to a snapshot taken before provisioning
|
|
470
|
+
- Fedora / Debian 12 / Ubuntu 24.04 live images
|
|
471
|
+
- Check with `LD_DEBUG=libs` / `GI_DEBUG` that nothing loads from host `/usr/lib`
|
|
472
|
+
except the excludelist.
|
|
473
|
+
- Check by hand: syntax highlighting (language-specs found), the file chooser
|
|
474
|
+
(schemas), icons, audio playback (GStreamer plugins), the embedded terminal (VTE),
|
|
475
|
+
single-instance forwarding (the `listen` gem / inotify), and the desktop launcher
|
|
476
|
+
pointing at the AppImage.
|
|
477
|
+
|
|
478
|
+
## Effort estimate
|
|
479
|
+
|
|
480
|
+
| Step | Effort |
|
|
481
|
+
|---|---|
|
|
482
|
+
| Code changes 1–3, 5, 7 | small (about half a day) |
|
|
483
|
+
| Ruby + gems in an AppDir, typelibs and data, AppRun, working locally | 2–4 days. Most of it is finding all the typelib-reached libs and data paths. |
|
|
484
|
+
| CI job + release upload + clean-machine testing | 1–2 days |
|
|
485
|
+
| Flatpak (manifest, gem sources, `host_cmd` wrapper over all external commands) | 3–5 days more, plus Flathub review |
|
|
486
|
+
|
|
487
|
+
## Recommended order
|
|
488
|
+
|
|
489
|
+
1. Code changes 1–3, 5, 7 (useful on their own).
|
|
490
|
+
2. Choose the build host (see "GTK version differences"; proposed Ubuntu 24.04).
|
|
491
|
+
If 22.04 is still wanted, run the test suite there first.
|
|
492
|
+
3. Write `scripts/build_appimage.sh` in a build-host container and get a working AppImage
|
|
493
|
+
locally. Test it on the clean VM.
|
|
494
|
+
4. CI build on tags plus a GitHub release asset. Update README.md's install section
|
|
495
|
+
("Download the AppImage", with `gem install` as the alternative).
|
|
496
|
+
5. Later: Flatpak/Flathub, with the `host_cmd` wrapper.
|
|
497
|
+
|
|
498
|
+
## DONE
|
|
499
|
+
|
|
500
|
+
- **Code changes 1, 2, 3, 7** (2026-11-19, `24a1a88`): `exe/vimamsa` and
|
|
501
|
+
`exe/run_tests.rb` load `lib/`/`ext/` next to the script; dead `ext/stridx` load
|
|
502
|
+
path removed; the desktop launcher runs `$APPIMAGE` when set (quoted per the
|
|
503
|
+
Desktop Entry spec); gemspec `required_ruby_version >= 3.1` (3.1 untested; the VM
|
|
504
|
+
runs 3.2). Tests: `tests/test_bundling.rb`. Code change 5 (the `ruby-lsp` binstub
|
|
505
|
+
on PATH) belongs to AppRun, so it comes with `scripts/build_appimage.sh`.
|
|
506
|
+
- **AppImage build script** (2026-11-19, `bc43676`): `scripts/appimage/build.sh`
|
|
507
|
+
(host, Docker) runs `scripts/appimage/build_in_container.sh` in the Ubuntu 24.04
|
|
508
|
+
image from `scripts/appimage/Dockerfile`. Output:
|
|
509
|
+
`build/appimage/Vimamsa-<version>-x86_64.AppImage`, **92 MB** (249 MB unpacked).
|
|
510
|
+
Builds the committed `HEAD` (`VMA_REF` to change); Ruby and appimagetool are cached
|
|
511
|
+
in `build/appimage/cache`, so a rebuild takes about 3 minutes.
|
|
512
|
+
- Ruby 3.4.9 built with `--enable-load-relative`; gems installed with it.
|
|
513
|
+
- Libraries: no linuxdeploy. The script seeds the list with `ruby`, every gem/stdlib
|
|
514
|
+
`.so`, the GStreamer plugins, the gdk-pixbuf loaders, the dconf GIO module and the
|
|
515
|
+
`.so` named in each typelib (read with `strings`), then follows `ldd` and copies
|
|
516
|
+
everything except an excludelist (glibc, libstdc++, GL/DRM/Vulkan, X11/core
|
|
517
|
+
xcb/Wayland client, fontconfig/freetype/harfbuzz, sound servers, zlib, expat).
|
|
518
|
+
`patchelf` sets an `$ORIGIN` RUNPATH on every bundled ELF file, so **AppRun sets no
|
|
519
|
+
`LD_LIBRARY_PATH`** and programs the editor starts don't load bundled libs. The
|
|
520
|
+
build fails if any bundled file has an unresolved library.
|
|
521
|
+
- All 56 typelibs of the build host are copied (2.9 MB).
|
|
522
|
+
- `ruby-lsp` / `rufo` are reached through wrappers in `usr/lib/vimamsa/bin` on
|
|
523
|
+
`PATH` (code change 5), not by putting the bundled `ruby` first on `PATH`.
|
|
524
|
+
- Packed with appimagetool continuous (static type-2 runtime: no libfuse2 needed).
|
|
525
|
+
- Tests:
|
|
526
|
+
- Clean `ubuntu:24.04` container (no GTK, no Ruby, no typelibs; only the host
|
|
527
|
+
libs a desktop has): `test_basic_editing.rb` 14/14 from the AppImage. Loaded
|
|
528
|
+
from outside the image (`LD_DEBUG=libs`): only the excludelist and what the
|
|
529
|
+
host's Mesa/harfbuzz pull in.
|
|
530
|
+
- Test VM (`$VM_NAME`), real GNOME Wayland desktop, the AppImage itself (FUSE-mounted):
|
|
531
|
+
full suite 390 passed, 1 failed (the known `TestDictation` failure), 6 skipped.
|
|
532
|
+
The launcher becomes `Exec="<path to>/Vimamsa-x86_64.AppImage" %F`.
|
|
533
|
+
|
|
534
|
+
- **Started programs get the user's environment** (2026-11-19, `bc43676`): AppRun
|
|
535
|
+
lists every variable it changes in `VMA_APPIMAGE_ENV` and keeps the old values in
|
|
536
|
+
`VMA_HOST_<name>`. After startup, `restore_host_env` (`lib/vimamsa/appimage_env.rb`,
|
|
537
|
+
called at the end of `Editor#start`) puts them back. GLib/GIO/GI keep what they read
|
|
538
|
+
at startup. Before restoring, it initializes the parts that read their variables
|
|
539
|
+
lazily: gdk-pixbuf loaders, the GSettings schema source, GIO modules, and GStreamer
|
|
540
|
+
(loaded and `Gst.init`ed even when audio is off, so a module enabled later still
|
|
541
|
+
finds the bundled plugins). The `ruby-lsp`/`rufo` wrappers unset `GEM_HOME` etc.
|
|
542
|
+
themselves. `VMA_REF=WORKTREE` builds include uncommitted changes. VM, from the
|
|
543
|
+
AppImage: 392 passed, 1 failed (`TestDictation`); `test_appimage_children_get_host_environment`
|
|
544
|
+
checks that no variable except PATH/APPDIR/APPIMAGE points into the image and
|
|
545
|
+
that VTE, `playbin`, pixbuf loading and `ruby-lsp` still work afterwards.
|
|
546
|
+
|
|
547
|
+
- **CI build and release** (2026-11-19, `1192898`): `.github/workflows/appimage.yml`. On
|
|
548
|
+
a `vX.Y.Z` tag (must match `version.rb`) it builds with `scripts/appimage/build.sh`,
|
|
549
|
+
runs `scripts/appimage/smoke_test.sh` (clean `ubuntu:24.04`: no GTK/Ruby, only the
|
|
550
|
+
libraries a desktop has), signs a build provenance attestation and attaches
|
|
551
|
+
`Vimamsa-x86_64.AppImage` + `.sha256` to the release. A fixed file name, so
|
|
552
|
+
README links to `releases/latest/download/Vimamsa-x86_64.AppImage`. Run by hand,
|
|
553
|
+
it only builds and tests (workflow artifact). appimagetool 1.9.1 and the type-2
|
|
554
|
+
runtime 20251108 are pinned by SHA-256. The smoke test found that the MIME
|
|
555
|
+
database must be bundled (gdk-pixbuf couldn't detect PNG without
|
|
556
|
+
shared-mime-info). Not yet run on GitHub: the first tag push is its first run.
|
|
557
|
+
|
|
558
|
+
## Follow-ups found while building
|
|
559
|
+
|
|
560
|
+
- **GTK modules from the host**: `libgtk-4` still looks in the host's
|
|
561
|
+
`/usr/lib/x86_64-linux-gnu/gtk-4.0/4.0.0` (print backends, media, IM modules). Fine
|
|
562
|
+
on 24.04-era hosts; check on a newer distro.
|
|
563
|
+
- **GStreamer size**: all of plugins-base/good are bundled (12 MB plus their deps).
|
|
564
|
+
Trimming to what playback/dictation need is possible later.
|
|
565
|
+
- **Gems are not pinned**: `gem install` resolves the newest matching versions
|
|
566
|
+
(Ruby-GNOME 4.3.9 here). Use a lockfile for reproducible releases.
|
|
567
|
+
- Not tested yet: another distro (Fedora/Arch), X11 session, non-US keyboard/IME,
|
|
568
|
+
HiDPI scaling.
|
|
569
|
+
|