landon
be6a2d6a8b
The launcher pointed at `Icon=story-editor`, a name that only the Breeze theme happened to ship, and only at 16 and 22 px -- so anywhere the desktop wanted a larger icon it fell back to something generic. assets/md-manuscript.svg is the source: a sheaf of manuscript pages, an amber chapter-title line over three of prose. Drawn in plain rounded rectangles because a finer design silts up into a grey smear at 16 px. It is rasterised to the eight sizes a desktop asks for, and the 256px PNG is compiled into the binary as the window icon, so the title bar and the task switcher carry it whether or not anything is installed. That costs no new dependency: eframe already pulls `image` with png decoding. A test decodes the bundled PNG, since a rename would otherwise show up only as a blank icon at runtime. Installation is now `./assets/install.sh` -- binary, icons, launcher and both cache refreshes, safe to re-run after a rebuild. The launcher is a file in the repository rather than a here-document in the instructions: pasting one into a terminal leaves the shell sat at a `>` prompt waiting for a terminator that never arrives, which is exactly what happened, and this way the launcher is versioned along with everything else. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GYSGPDwkSzhm4qLqjCbqxU
305 lines
11 KiB
Markdown
305 lines
11 KiB
Markdown
# Installing md-manuscript on a Surface tablet (Debian 12 "Bookworm")
|
||
|
||
These steps build the app from source and set it up for touch use on a Microsoft
|
||
Surface running Debian 12. They assume the **GNOME** desktop, with **XFCE**
|
||
equivalents called out where they differ (see *[Add md-manuscript to the XFCE
|
||
menu](#add-md-manuscript-to-the-xfce-menu)*). You do **not** need the
|
||
`linux-surface` custom kernel for this app — any working Debian 12 desktop is
|
||
fine.
|
||
|
||
Everything is done in a terminal. If your Surface is detached from its keyboard,
|
||
turn on the on-screen keyboard first (see [Surface tips](#surface-specific-tips)).
|
||
|
||
---
|
||
|
||
## 1. One-time system setup
|
||
|
||
### a. Build tools
|
||
|
||
Debian 12 ships Rust 1.63 in `apt`, which is **too old** for this project.
|
||
Install the Rust toolchain with `rustup` instead, plus a C linker.
|
||
|
||
```sh
|
||
sudo apt update
|
||
sudo apt install -y build-essential curl git
|
||
|
||
# Install rustup (choose option 1, the default, when prompted)
|
||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||
|
||
# Load cargo into the current shell (or just open a new terminal)
|
||
. "$HOME/.cargo/env"
|
||
|
||
rustc --version # should print 1.8x or newer
|
||
```
|
||
|
||
### b. Runtime GUI libraries
|
||
|
||
The compiled binary loads its graphics/windowing libraries at runtime (it links
|
||
against only libc/libgcc). Most are already present under GNOME, but install the
|
||
full set so it runs on both Wayland and X11:
|
||
|
||
```sh
|
||
sudo apt install -y \
|
||
libgl1 libegl1 libgl1-mesa-dri \
|
||
libwayland-client0 libwayland-egl1 libwayland-cursor0 \
|
||
libxkbcommon0 libxkbcommon-x11-0 \
|
||
libx11-6 libx11-xcb1 libxcursor1 libxi6 libxrandr2 libxinerama1 libxrender1
|
||
```
|
||
|
||
The **📂 Browse** buttons open native file dialogs through the XDG Desktop
|
||
Portal. On GNOME this is already installed, but if the dialogs don't appear,
|
||
ensure the portal and a file-chooser backend are present:
|
||
|
||
```sh
|
||
sudo apt install -y xdg-desktop-portal xdg-desktop-portal-gtk
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Get the source onto the tablet
|
||
|
||
Copy the `md-manuscript` project directory to the tablet (via USB, `scp`, or a
|
||
sync tool), **or** clone it if you've pushed it to a git remote:
|
||
|
||
```sh
|
||
# Example if you pushed it somewhere:
|
||
git clone <your-repo-url> ~/md-manuscript
|
||
```
|
||
|
||
The rest of these steps assume the source is at `~/md-manuscript`.
|
||
|
||
---
|
||
|
||
## 3. Build
|
||
|
||
```sh
|
||
cd ~/md-manuscript
|
||
cargo build --release
|
||
```
|
||
|
||
The first build downloads dependencies and takes a few minutes on Surface
|
||
hardware. The result is `~/md-manuscript/target/release/md-manuscript`.
|
||
|
||
> If the build stops with *"rustc 1.87.0 is not supported by … image@0.25.x"*,
|
||
> your Rust is older than expected — run `rustup update` and rebuild.
|
||
|
||
---
|
||
|
||
## 4. Install the binary and a launcher
|
||
|
||
Put the binary on your `PATH` and add a desktop app entry so it appears in your
|
||
applications menu (GNOME app grid / XFCE Whisker Menu) and can be pinned for
|
||
touch:
|
||
|
||
```sh
|
||
./assets/install.sh
|
||
```
|
||
|
||
That puts the binary on your `PATH`, installs the icon at every size the desktop
|
||
might ask for, and adds the launcher — then refreshes both caches. It is safe to
|
||
re-run after every rebuild, which is how you pick up a new version. Installing
|
||
somewhere else is `PREFIX=/usr/local sudo ./assets/install.sh`.
|
||
|
||
<details>
|
||
<summary>What it does, if you would rather do it by hand</summary>
|
||
|
||
```sh
|
||
install -Dm755 target/release/md-manuscript ~/.local/bin/md-manuscript
|
||
|
||
for size in 16 22 24 32 48 64 128 256; do
|
||
install -Dm644 "assets/icons/hicolor/${size}x${size}/apps/md-manuscript.png" \
|
||
~/.local/share/icons/hicolor/${size}x${size}/apps/md-manuscript.png
|
||
done
|
||
install -Dm644 assets/icons/hicolor/scalable/apps/md-manuscript.svg \
|
||
~/.local/share/icons/hicolor/scalable/apps/md-manuscript.svg
|
||
|
||
install -Dm644 assets/md-manuscript.desktop \
|
||
~/.local/share/applications/md-manuscript.desktop
|
||
|
||
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor 2>/dev/null || true
|
||
update-desktop-database ~/.local/share/applications 2>/dev/null || true
|
||
```
|
||
|
||
The launcher is `assets/md-manuscript.desktop`, kept in the repository and
|
||
copied into place rather than typed out at the prompt — a here-document is an
|
||
awkward thing to paste into a terminal, and this way the launcher is versioned
|
||
along with everything else.
|
||
|
||
</details>
|
||
|
||
`Icon=md-manuscript` in the launcher is a *name*, not a path: the desktop looks
|
||
it up in the icon theme and picks whichever size it wants, which is why the whole
|
||
set gets installed rather than one file. `StartupWMClass` matches the running
|
||
window to the launcher, so a pinned icon highlights rather than spawning a second
|
||
entry.
|
||
|
||
The window carries the icon itself as well — the 256px PNG is compiled into the
|
||
binary — so the title bar and the task switcher show it even before any of this
|
||
is installed.
|
||
|
||
### Regenerating the icon
|
||
|
||
`assets/md-manuscript.svg` is the source. After editing it, rebuild the PNG set
|
||
(ImageMagick rasterises the SVG; Pillow does the downscaling, which is markedly
|
||
cleaner at 16 and 24 px):
|
||
|
||
```sh
|
||
python3 - <<'REGEN'
|
||
import os, subprocess
|
||
from PIL import Image
|
||
subprocess.run(["convert", "-background", "none", "-density", "1200",
|
||
"assets/md-manuscript.svg", "-resize", "512x512",
|
||
"/tmp/md-manuscript-master.png"], check=True)
|
||
im = Image.open("/tmp/md-manuscript-master.png").convert("RGBA")
|
||
for size in (16, 22, 24, 32, 48, 64, 128, 256):
|
||
d = f"assets/icons/hicolor/{size}x{size}/apps"
|
||
os.makedirs(d, exist_ok=True)
|
||
im.resize((size, size), Image.LANCZOS).save(f"{d}/md-manuscript.png")
|
||
REGEN
|
||
cp assets/md-manuscript.svg assets/icons/hicolor/scalable/apps/md-manuscript.svg
|
||
cargo build --release # the 256px PNG is baked into the binary
|
||
```
|
||
|
||
Make sure `~/.local/bin` is on your `PATH` (it is by default on Debian 12 if the
|
||
directory exists at login — otherwise add this to `~/.bashrc` and re-login):
|
||
|
||
```sh
|
||
export PATH="$HOME/.local/bin:$PATH"
|
||
```
|
||
|
||
You can now launch **md-manuscript** by tapping its icon, or run
|
||
`md-manuscript` from a terminal.
|
||
|
||
---
|
||
|
||
## Add md-manuscript to the XFCE menu
|
||
|
||
XFCE reads the same `~/.local/share/applications/md-manuscript.desktop` launcher
|
||
from step 4, so the app already appears under **Office** in the applications
|
||
menu. To pin it as a favourite:
|
||
|
||
**Whisker Menu (Favourites).** The Favourites feature lives in the *Whisker
|
||
Menu* (the modern XFCE menu), not the classic *Applications Menu* plugin. Open
|
||
the Whisker Menu, type `md-manuscript` (or find it under *Office*), then
|
||
**right-click it → "Add to Favorites."** It moves to the Favourites column at the
|
||
top-left of the menu, where you can right-click to reorder or remove it.
|
||
|
||
If your panel still has the classic *Applications Menu* (which has no
|
||
favourites), install and switch to Whisker:
|
||
|
||
```sh
|
||
sudo apt install -y xfce4-whiskermenu-plugin
|
||
```
|
||
|
||
then right-click the panel → *Panel → Add New Items… → Whisker Menu* (and remove
|
||
the old menu plugin).
|
||
|
||
**Panel launcher (alternative).** To place it directly on the panel: right-click
|
||
the panel → *Panel → Add New Items… → Launcher → Add*, then right-click the new
|
||
launcher → *Properties*, press **＋**, and pick **md-manuscript** from the list.
|
||
|
||
**Desktop icon (alternative).** Copy the launcher onto the desktop:
|
||
|
||
```sh
|
||
cp ~/.local/share/applications/md-manuscript.desktop ~/Desktop/
|
||
```
|
||
|
||
(right-click it → *Allow Launching* the first time, if prompted).
|
||
|
||
If it doesn't show up in the menu, refresh the database and restart the panel:
|
||
|
||
```sh
|
||
update-desktop-database ~/.local/share/applications 2>/dev/null || true
|
||
xfce4-panel -r
|
||
```
|
||
|
||
---
|
||
|
||
## 5. First run
|
||
|
||
1. In the top bar, set **Workspace** (default `~/Manuscript`) and tap **Open** —
|
||
the folder is created if missing.
|
||
2. Tap **Init git** once to version-control the workspace.
|
||
3. To sync across devices, add a remote yourself, then use the **⟳ Sync** button:
|
||
```sh
|
||
cd ~/Manuscript
|
||
git remote add origin <url>
|
||
git push -u origin main
|
||
```
|
||
You'll also want to set your git identity once on the tablet:
|
||
```sh
|
||
git config --global user.name "Your Name"
|
||
git config --global user.email "you@example.com"
|
||
```
|
||
|
||
---
|
||
|
||
## Surface-specific tips
|
||
|
||
**On-screen keyboard (detached from Type Cover).**
|
||
GNOME Settings → *Accessibility* → *Typing* → turn on **Screen Keyboard**; it
|
||
pops up automatically when you tap a text field. XFCE has no built-in one — install
|
||
`onboard` (`sudo apt install -y onboard`) and start it manually. For a
|
||
terminal-heavy setup you may find it easier to attach the keyboard for the
|
||
one-time install.
|
||
|
||
**HiDPI / tiny or huge UI.**
|
||
Surface screens are very high resolution. The app follows the desktop's scale
|
||
factor, so set it once in GNOME Settings → *Displays* → **Scale** (enable
|
||
*Fractional Scaling* if you want values like 150%/175%). On XFCE, use *Settings →
|
||
Appearance → Fonts → Custom DPI* and/or *Settings → Display*, or raise `Xft/DPI`
|
||
in *Settings Editor*. Because XFCE runs on X11, you can also launch with an
|
||
explicit factor (this works on GNOME-under-X11 too):
|
||
```sh
|
||
WINIT_X11_SCALE_FACTOR=1.75 md-manuscript
|
||
```
|
||
|
||
**Touch gestures.**
|
||
- **Tap** a file name to open it.
|
||
- **Reorder** by pressing the `⠿` handle and dragging up/down with your finger.
|
||
- **Scroll** the file list or editor with a one-finger drag.
|
||
|
||
**Wayland vs X11.**
|
||
GNOME on Debian 12 defaults to Wayland; the app supports it natively. If you hit
|
||
a rendering glitch, log out and pick *"GNOME on Xorg"* from the gear menu on the
|
||
login screen, or force X11 for one launch:
|
||
```sh
|
||
WINIT_UNIX_BACKEND=x11 md-manuscript
|
||
```
|
||
XFCE is X11-only on Debian 12, so there is no Wayland toggle to worry about and
|
||
the `WINIT_X11_SCALE_FACTOR` variable above applies directly.
|
||
|
||
---
|
||
|
||
## Updating
|
||
|
||
```sh
|
||
cd ~/md-manuscript
|
||
git pull # if you cloned it; otherwise re-copy the source
|
||
cargo build --release
|
||
install -Dm755 target/release/md-manuscript ~/.local/bin/md-manuscript
|
||
```
|
||
|
||
## Uninstall
|
||
|
||
```sh
|
||
rm -f ~/.local/bin/md-manuscript
|
||
rm -f ~/.local/share/applications/md-manuscript.desktop
|
||
# Your manuscripts in ~/Manuscript and config in ~/.config/md-manuscript are left intact.
|
||
```
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Fix |
|
||
|---|---|
|
||
| `error while loading shared libraries: libGL.so.1` (or similar) | Install the runtime libraries in step 1b. |
|
||
| Window fails with *"neither WAYLAND_DISPLAY nor DISPLAY is set"* | You're in a text-only session/SSH; run it from the tablet's graphical desktop. |
|
||
| **📂 Browse** buttons do nothing / no dialog appears | Install `xdg-desktop-portal` and `xdg-desktop-portal-gtk` (step 1b); you can still type paths by hand. |
|
||
| Build error mentioning `rustc … is not supported` | `rustup update`, then `cargo build --release` again. |
|
||
| `cargo: command not found` | Run `. "$HOME/.cargo/env"` or open a new terminal after installing rustup. |
|
||
| UI text far too small/large | Adjust GNOME *Displays → Scale* (or XFCE *Appearance → Fonts → Custom DPI*), or set `WINIT_X11_SCALE_FACTOR` (X11). |
|
||
| Not in the XFCE menu / no **Add to Favorites** | Run `update-desktop-database ~/.local/share/applications` and `xfce4-panel -r`; favourites need the *Whisker Menu* (`xfce4-whiskermenu-plugin`), not the classic Applications Menu. |
|
||
| **⟳ Sync** does nothing / errors in the Log panel | Set `git config --global user.name/user.email`, and ensure the `origin` remote and your SSH/HTTPS credentials are configured. |
|