libinput: Helper tools

Helper tools

libinput provides a couple of tools to query state and events.

Two of these tools are usually installed, others are Developer tools only.

# User tools

libinput ships with two tools to gather information about devices: libinput-list-devices and libinput-debug-events. Both tools must be run as root to have access to the kernel's `/dev/input/event*` device files.

## libinput-list-devices

The libinput-list-devices tool shows information about devices 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.

    $ sudo libinput-list-devices
    [...]
    Device:           SynPS/2 Synaptics TouchPad
    Kernel:           /dev/input/event4
    Group:            9
    Seat:             seat0, default
    Size:             97.33x66.86mm
    Capabilities:     pointer
    Tap-to-click:     disabled
    Tap drag lock:    disabled
    Left-handed:      disabled
    Nat.scrolling:    disabled
    Middle emulation: n/a
    Calibration:      n/a
    Scroll methods:   *two-finger
    Click methods:    *button-areas clickfinger
    [...]

The above listing shows example output for a touchpad. The libinput-list-devices tool lists general information about the device (the kernel event node) but also the configuration options. If an option is "n/a" it does not exist on this device. Otherwise, the tool will show the default configuration for this device, for options that have more than a 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.

## libinput-debug-events

This is an installed version of the event-debug developer tool. It prints events from devices and can help to identify why a device behaves different than expected.

    $ sudo libinput-debug-events --enable-tapping --set-click-method=clickfinger

See the man page or the `–help` output for information about the available options.

# Developer tools

The two most common tools used by developers are event-debug and event-gui.

## event-debug

This is the in-tree version of the libinput-debug-events tool and is linked to allow for easy debugging (i.e. it avoids libtool shenanigans). The code is the same. For debugging, run it against a single device only and enable the –verbose flag. This will print the various state machine transitions in addition to the events.

    $ sudo ./tools/event-debug --verbose --device /dev/input/event3

See the `–help` output for information about the available options.

## event-gui

A simple GTK-based graphical tool that shows the behavior and location of touch events, pointer motion, scroll axes and gestures. Since this tool gathers data directly from libinput, it is thus suitable for pointer-acceleration testing.

    $ sudo ./tools/event-gui

See the `–help` output for information about the available options.

Note
  The `–grab` flag puts an exclusive `EVIOCGRAB` on the device to avoid interference with the desktop while testing.