From 9478050eee12245499635e34c6ffe2940f7fb72b Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Tue, 10 Jul 2018 18:00:07 +1000 Subject: [PATCH] doc: add a subsection on how to use libinput record --autorestart Signed-off-by: Peter Hutterer (cherry picked from commit 529755e18f7b42b835ea33b74a1bc3218cda8841) --- doc/tools.dox | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc/tools.dox b/doc/tools.dox index 5654e329..519c9898 100644 --- a/doc/tools.dox +++ b/doc/tools.dox @@ -202,6 +202,35 @@ have captured the bug. More arguments are available, see the **libinput-record(1)** and **libinput-replay(1)** man pages. +@subsection libinput-record-autorestart libinput record's autorestart feature + +`libinput record` often collects thousands of events per minute. However, +the output of `libinput record` usually needs to be visually inspected +or replayed in realtime on a developer machine. It is thus imperative that +the event log is kept as short as possible. + +For bugs that are difficult to reproduce use +`libinput record --autorestart=2 --output-file=recording.yml`. +All events will be recorded to a file named +`recording.yml.` and whenever the device does not +send events for 2 seconds, a new file is created. This helps to keep +individual recordings short. + +To use the `--autorestart` option correctly: +- run `libinput record --autorestart=2 --output-file=.yml`. + You may provide a timeout other than 2 if needed. +- use the device to reproduce the bug, pausing frequently for 2s and longer + to rotate the logs +- when the bug triggers, **immediately stop using the device** and wait + several seconds for the log to rotate +- Ctrl+C the `libinput record` process without using the device + again. Attach the **last recording** to the bug report. + +If you have to use the recorded device to stop `libinput record` (e.g. to +switch windows), remember that this will cause a new recording to be +created. Thus, attach the **second-to-last recording** to the bug report +because this one contains the bug trigger. + @subsection libinput-record-multiple Recording multiple devices at once In some cases, an interaction between multiple devices is the cause for a