diff options
Diffstat (limited to 'patches/README')
| -rw-r--r-- | patches/README | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/patches/README b/patches/README new file mode 100644 index 0000000..cd4e12a --- /dev/null +++ b/patches/README @@ -0,0 +1,133 @@ +ttym patches +============ + +Each patch is a unified diff against the pristine base. Apply with: + + cd ttym + patch -p1 < patches/ttym-<name>-2.0.diff + +Then rebuild: + + rm -f config.h ; make + +To get every feature at once, skip the individual patches entirely and +apply ttym-full-2.0.diff -- one combined diff, no conflicts to resolve. +See "The full build" below. + + +The full build +-------------- + + ttym-full-2.0.diff + Every feature in a single patch: persist-alert, flash, notify, + logging, hooks, bar-styles and config-file, with all inter-patch + conflicts already resolved. Apply it to the pristine base and + rebuild: + + patch -p1 < patches/ttym-full-2.0.diff + rm -f config.h ; make + + This is the recommended route to the full-featured build. It is + equivalent to stacking all seven feature patches below and hand- + resolving every collision, but deterministic and conflict-free. + Use the individual patches only when you want a specific subset. + + +Available patches +----------------- + + ttym-persist-alert-2.0.diff + After a countdown completes, keep ringing the bell every ~1.5s + until any key is pressed. Foreground-only; backgrounded runs + fall through. Adds: --no-persist flag, ALERT_PERSIST knob. + + ttym-flash-2.0.diff [requires persist-alert] + Add reverse-video terminal flash to the persistent alert loop. + Adds: --flash on|off flag, FLASH knob. + + ttym-notify-2.0.diff + One-shot desktop notification and sound on countdown completion, + plus a MESSAGE positional argument piped through {title}/{msg} + placeholders. Adds: TITLE, NOTIFY_CMD, SOUND_CMD knobs. + + ttym-logging-2.0.diff + TSV log at ~/.config/ttym/ttym.log, +tag extraction, the -r + reader (-n, --raw), and --stats (today|week|month|all). Adds + one-shot directory migration from ~/.config/timer/. + Adds: -c TEXT flag. + + ttym-hooks-2.0.diff + Optional executables at ~/.config/ttym/hooks/{on_start,on_done, + on_quit} invoked with: mode duration_seconds comment. + Adds: -c TEXT flag (passed as 3rd hook arg). + + ttym-bar-styles-2.0.diff + Eight built-in bar styles (unicode, ascii, hash, dots, line, + block, arrow, minimal) with locale-aware auto-detect. + Adds: --bar STYLE flag, BAR_STYLE knob. + + ttym-config-file-2.0.diff [capstone -- see Dependencies] + Runtime config at ~/.config/ttym/config (key = value), auto- + generated and self-documenting on first run. Exposes eight keys: + bar_fill, bar_empty, bar_style, flash, alert_persist, title, + notify_cmd, sound_cmd. A system-wide /etc/ttym.conf is read + first. Because it wires up knobs owned by other patches, it must + be applied LAST. + + +Dependencies +------------ + +flash depends on persist-alert. + +config-file is the capstone: it reads knobs introduced by persist- +alert, flash, notify, logging and bar-styles, and extends a usage() +line added by hooks -- so all six must be applied before it. Apply +config-file last. + +All other patches are independent of each other and of the base. + + +Stacking +-------- + +The simplest route to the full build is ttym-full-2.0.diff (see "The +full build" above). The notes here apply only when stacking the +feature patches by hand to assemble a subset. + +Every patch in this directory applies and compiles cleanly against the +pristine base -- except flash, which builds on persist-alert, and +config-file, the capstone, which builds on six other patches (see +Dependencies). That is the property the verification step guarantees. + +Combining multiple optional patches will produce conflicts at shared +regions: the Config struct, usage(), the getopt() option string, and +in some cases #include lines. This is normal suckless territory -- +resolve by hand, or apply ttym-full-2.0.diff instead. The base is laid +out so most patches add their new code in fresh sections (before +usage(), before main()) where they do not collide; the inevitable +collisions are in points where every patch must add a line or field. + +Recommended order when stacking: + + persist-alert -> flash -> notify -> logging -> hooks -> + bar-styles -> config-file + +config-file must come last -- after bar-styles in particular, since it +overrides the resolved bar glyphs. Apply, resolve any .rej files, +rebuild. + + +Authoring new patches +--------------------- + +Match the discipline used here: + + - Add compile-time knobs to config.def.h, never inline in ttym.c. + - Update usage() in the same hunk as the option parser change, so + `timer -h` never drifts from what the build actually supports. + - Verify with `patch -p1` against a fresh copy of the base -- or, + for a patch with prerequisites, the base plus those -- and confirm + the result compiles before publishing. + - When the patch set changes, regenerate ttym-full-2.0.diff so the + one-shot full build stays in sync. |