fix(runtime): make startup and GTK installation explicit

README.md

@@ -41,15 +41,20 @@ XIM supports `UTF8_STRING` and `COMPOUND_TEXT`. Position clients place the
 popup from `XNSpotLocation`; otherwise XIM placement falls back to the bottom
 of the focus or client window.
 
+The popup is an X11 window, XIM is X11-only, and GTK popup placement converts
+the GTK caret to X11 root coordinates. There is no native Wayland popup
+surface or Wayland caret positioning. GTK and IBus clients can still use
+inline preedit where their display environment supports it.
+
 ## Build and test
 
-Docker is the supported build environment:
+Initialize the bundled test library, then use the pinned Docker environment
+for a reproducible build:
 
 ```sh
 git submodule update --init
 make docker-image
 make docker-build
-make docker-check
 ```
 
 Build output:
@@ -59,9 +64,32 @@ strans              daemon with IBus and XIM frontends
 gtk/im-strans.so    GTK 3 frontend module
 ```
 
-Use `make docker-check TESTARGS=hangul` to run selected C tests. Native
-`make all`, `make check`, and `make bench` are also available when the
-dependencies listed in [`Dockerfile`](Dockerfile) are installed.
+Tests have three tiers:
+
+```sh
+make check          # generated-map validation and focused unit tests
+make check-live     # one IBus, GTK, XIM, and IPC daemon smoke
+make check-stress   # randomized, capacity, collision, failure, and restart tests
+```
+
+`UNITARGS` filters only the focused C unit suite, for example
+`make check UNITARGS=hangul`. It does not select or skip live and stress
+tests. `make docker-check` force-rebuilds and runs all three tiers in the
+container; run `make docker-image` first after changing `Dockerfile`.
+
+Native Linux builds require a C toolchain, Make, pkg-config, Python 3, and
+cmp/diff, plus:
+
+- Plan 9 port (`9c`, `9l`, `libthread`, and `libbio`);
+- D-Bus development files;
+- XCB, XCB RandR, xcb-imdkit, xkbcommon, and xkbcommon-x11;
+- Pango, PangoCairo, Cairo, and Fontconfig;
+- GTK 3, plus libibus and Xlib for the live clients;
+- Xvfb for the X11 live tests;
+- a working `C.UTF-8` locale and fonts covering Latin, CJK, and emoji.
+
+The package names used by the canonical Arch Linux image are listed in
+[`Dockerfile`](Dockerfile).
 
 ## Run
 
@@ -75,12 +103,21 @@ from the build tree:
 ./strans map
 ```
 
+`run.sh` stays in the foreground and replaces itself with the daemon. Stop it
+with `Ctrl-C` or let a service supervisor own it. It neither finds nor kills
+other `strans` processes. Endpoint collisions and requested frontend startup
+failures make the process exit non-zero.
+
+The build does not copy or install the daemon or its data. `./strans DIR`
+opens `hira.map`, `kata.map`, `telex.map`, `kanji.dict`, `emoji.dict`, and
+`hanja.dict` from `DIR` at runtime; `run.sh` passes the tracked `map/`
+directory. Only the GTK subdirectory has install and uninstall targets.
+
 Pango shapes the complete string and selects glyph fallback from the system
 font set.
 
 The popup renderer uses Pango/PangoCairo and Cairo. When `DISPLAY` is set,
-`strans` starts its XIM worker in the same process. `run.sh` restarts the
-existing `strans` process owned by the current user.
+`strans` starts its XIM worker in the same process.
 
 Configure clients as needed:
 
@@ -90,11 +127,21 @@ export XMODIFIERS=@im=strans
 
 # GTK 3 module
 doas make -C gtk install
+export GTK_IM_MODULE=strans
 
 # IBus client example
 GLFW_IM_MODULE=ibus kitty
 ```
 
+The GTK module directory is derived from GTK's pkg-config `libdir` and binary
+version. It can be overridden with `GTK_MODULE_DIR`; `DESTDIR` staging is
+supported and deliberately skips the host module-cache update. Remove a
+native installation with:
+
+```sh
+doas make -C gtk uninstall
+```
+
 strans provides its own IBus endpoint; `ibus-daemon` and fcitx are not
 required. Without `DISPLAY`, the daemon and IBus frontend still work, but XIM
 is not started and the popup is disabled.
@@ -112,6 +159,13 @@ make verify-map
 See [`map/README`](map/README) for Hanja import and Japanese dictionary
 generation.
 
+## Benchmark
+
+`make bench` builds `bench/bench`. With the daemon stopped, `./bench.sh` starts
+one build-tree instance, warms it up, and records the workload with Linux
+`perf`. It requires `perf` and permission to profile the daemon, and writes
+`bench/perf.data`.
+
 ## Licensing
 
 Third-party license notices are in [`LICENSES`](LICENSES). The repository does