md-manuscript/INSTALL-debian12-surface.md

# 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 with the GNOME desktop. 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 GNOME app entry so it appears in the
Activities/app grid and can be pinned to the dash (handy for touch):

```sh
# 4a. Binary
install -Dm755 target/release/md-manuscript ~/.local/bin/md-manuscript

# 4b. Desktop launcher
mkdir -p ~/.local/share/applications
cat > ~/.local/share/applications/md-manuscript.desktop <<'EOF'
[Desktop Entry]
Type=Application
Name=md-manuscript
Comment=Draggable markdown manuscript editor with git sync and ODT export
Exec=md-manuscript
Icon=text-editor
Categories=Office;TextEditor;
Terminal=false
EOF

# 4c. Refresh the app list
update-desktop-database ~/.local/share/applications 2>/dev/null || true
```

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.

---

## 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. For 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%). If you run under X11 and
the size is still off, launch with an explicit factor:
```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
```

---

## 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 set `WINIT_X11_SCALE_FACTOR` (X11). |
| **⟳ 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. |