fdo-mirrors/libinput
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libinput.git synced 2026-01-07 00:40:13 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: improve the 'tools' page

Browse source 
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer 2018-06-04 09:20:15 +10:00
parent 085a33d545
commit f82e77830f
1 changed files with 79 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

98
doc/tools.dox
View file

@ -1,16 +1,25 @@
/**
@page tools Helper tools
libinput provides a `libinput` tool to query state and events.
The two most common invocations are
@ref libinput-list-devices and @ref libinput-debug-events. The @ref
libinput-record tools are used to analyze and reproduce events sequences on
developer machines, particularly useful when a user experiences a bug.
libinput provides a `libinput` tool to query state and events. This tool
takes a subcommand as argument, similar to the **git** command. A full
explanation of the various commands available in the libinput tool is
available in the **libinput(1)** man page.
A full explanation of the various commands available in the libinput tool is
available in the libinput(1) man page. Generally, the tool must be run as
root to have access to the kernel's @c /dev/input/event*
device files.
The most common tools used are:
- `libinput list-devices`: to list locally available devices, see @ref
libinput-list-devices "here"
- `libinput debug-events`: to monitor and debug events, see @ref
libinput-debug-events "here"
- `libinput debug-gui`: to visualize events, see @ref libinput-debug-gui
"here"
- `libinput record`: to record an event sequence for replaying, see @ref
libinput-record "here"
- `libinput measure`: measure properties on a kernel device, see @ref
libinput-measure "here"
Most the tools must be run as root to have access to the kernel's @c
/dev/input/event* device files.
@section libinput-list-devices libinput list-devices
@ -19,6 +28,9 @@ recognized by libinput and can help identifying why a device behaves
different than expected. For example, if a device does not show up in the
output, it is not a supported input device.
@note This tool does **not** show your desktop's configuration, just the
libinput built-in defaults.
@verbatim
$ sudo libinput list-devices
[...]
@ -48,9 +60,6 @@ binary state all available options are listed, with the default one prefixed
with an asterisk (*). In the example above, the default click method is
button-areas but clickinger is available.
Note that the default configuration may differ from the configuration
applied by the desktop environment.
@note This tool is intended to be human-readable and may change its output
at any time.
@ -62,8 +71,46 @@ to identify why a device behaves different than expected.
$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger
@endverbatim
See the libinput(1) man page or the @c --help output for information about
the available options.
All configuration options (enable/disable tapping,
etc.) are available as commandline arguments. To reproduce the event
sequence as your desktop session sees it, ensure that all options are turned
on or off as required. See the **libinput-debug-events(1)** man page or the
`--help` output for information about the available options.
@note When submitting a bug report, always use the `--verbose` flag to get
additional information: `libinput debug-events --verbose <other options>`
An example output from this tool may look like the snippet below.
@verbatim
$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger
-event2 DEVICE_ADDED Power Button seat0 default group1 cap:k
-event5 DEVICE_ADDED Video Bus seat0 default group2 cap:k
-event0 DEVICE_ADDED Lid Switch seat0 default group3 cap:S
-event1 DEVICE_ADDED Sleep Button seat0 default group4 cap:k
-event4 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=3 seat0 default group5 cap:
-event11 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=7 seat0 default group6 cap:
-event12 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=8 seat0 default group7 cap:
-event13 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=9 seat0 default group8 cap:
-event14 DEVICE_ADDED HDA Intel HDMI HDMI/DP,pcm=10 seat0 default group9 cap:
-event19 DEVICE_ADDED Integrated Camera: Integrated C seat0 default group10 cap:k
-event15 DEVICE_ADDED HDA Intel PCH Dock Mic seat0 default group11 cap:
-event16 DEVICE_ADDED HDA Intel PCH Mic seat0 default group12 cap:
-event17 DEVICE_ADDED HDA Intel PCH Dock Headphone seat0 default group13 cap:
-event18 DEVICE_ADDED HDA Intel PCH Headphone seat0 default group14 cap:
-event6 DEVICE_ADDED ELAN Touchscreen seat0 default group15 cap:t size 305x172mm ntouches 10 calib
-event3 DEVICE_ADDED AT Translated Set 2 keyboard seat0 default group16 cap:k
-event20 DEVICE_ADDED SynPS/2 Synaptics TouchPad seat0 default group17 cap:pg size 100x76mm tap(dl off) left scroll-nat scroll-2fg-edge click-buttonareas-clickfinger dwt-on
-event21 DEVICE_ADDED TPPS/2 IBM TrackPoint seat0 default group18 cap:p left scroll-nat scroll-button
-event7 DEVICE_ADDED ThinkPad Extra Buttons seat0 default group19 cap:k
-event20 POINTER_MOTION +3.62s 2.72/ -0.93
event20 POINTER_MOTION +3.63s 1.80/ -1.42
event20 POINTER_MOTION +3.65s 6.16/ -2.28
event20 POINTER_MOTION +3.66s 6.42/ -1.99
event20 POINTER_MOTION +3.67s 8.99/ -1.42
event20 POINTER_MOTION +3.68s 11.30/ 0.00
event20 POINTER_MOTION +3.69s 21.32/ 1.42
@endverbatim
@section libinput-debug-gui libinput debug-gui
@ -72,11 +119,16 @@ touch events, pointer motion, scroll axes and gestures. Since this tool
gathers data directly from libinput, it is thus suitable for
pointer-acceleration testing.
@note This tool does **not** use your desktop's configuration, just the
libinput built-in defaults.
@verbatim
$ sudo libinput debug-gui
$ sudo libinput debug-gui --enable-tapping
@endverbatim
See the libinput(1) man page or the @c --help output for information about
As with @ref libinput-debug-events, all options must be specified on the
commandline to emulate the correct behavior.
See the **libinput-debug-gui(1)** man page or the `--help` output for information about
the available options.
@section libinput-record libinput record and libinput replay
@ -123,7 +175,7 @@ Without arguments, `libinput record` displays the available devices and lets
the user select one. Supply the number (17 in this case for
`/dev/input/event17`) and the tool will print the device information and
events to the file it is redirected to. More arguments are available, see
the `libinput-record` man page.
the **libinput-record(1)** man page.
Reproduce the bug, ctrl+c and attach the output file to a bug report.
For data protection, `libinput record` obscures key codes by default, any
@ -147,8 +199,8 @@ sequence again, Ctrl+C stops it and removes the virtual device.
Users are advised to always replay a recorded event sequence to ensure they
have captured the bug.
More arguments are available, see the `libinput-record` and
`libinput-replay` man pages.
More arguments are available, see the **libinput-record(1)** and
**libinput-replay(1)** man pages.
@subsection libinput-record-multiple Recording multiple devices at once
@ -174,4 +226,12 @@ Replaying events is the same as for a single recording:
$ sudo libinput replay touchpad-bug.log
@endverbatim
@subsection libinput-measure Measuring device properties with libinput measure
The `libinput measure` tool is a multiplexer for various sub-tools that can
measure specific properties on the device. These tools generally measure one
thing and one thing only and their usage is highly specific to the tool.
Please see the **libinput-measure(1)** man page for information about what
tools are available and the man page for each respective tool.
*/