https://gitlab.freedesktop.org/libinput/libinput/issues/new
.. note:: libinput has lots of users but very few developers. It is in your own
- interested to follow these steps precisely to ensure your bug can be
+ interested to follow the steps here precisely to ensure your bug can be
dealt with efficiently.
-When reporting bugs against libinput, please follow the instructions below
-and provide the required data. You will need:
+When reporting bugs against libinput, you will need:
- a reliable :ref:`reproducer <reporting_bugs_reproducer>` for the bug
- an :ref:`evemu recording <evemu>` of the device while the bug is reproduced
Obtaining the libinput version
------------------------------------------------------------------------------
-If your libinput version is older than the current stable branch, you will
-get asked to try the latest version. If you run a distribution-provided
+If your libinput version is older than the current stable branch, please try
+the latest version. If you run a distribution-provided
libinput, use the package manager to get the **full** package name and
version of libinput, e.g.
The output is textual and can help identify whether the bug is in libinput
at all. Note that any configuration options you have set must be specified
on the commandline, see the :ref:`libinput-debug-events`
-"libinput-debug-events" man page. Use the ``--verbose`` flag to get more
-information about how libinput processes events.
+man page. Use the ``--verbose`` flag to get more information about how
+libinput processes events.
If the bug cannot be reproduced with the :ref:`libinput-debug-events` helper,
even with the correct configuration options set, it is likely not a bug in
When you file a bug, please attach the following information:
-- a virtual description of your input device, see :ref:`evemu`. This is the
- most important piece of information, do not forget it!
+- a virtual description of your input device, see :ref:`libinput-record`.
+ This is the most important piece of information, do not forget it!
- the output from udevadm info, see :ref:`udev_info`.
- the vendor model number of your laptop (e.g. "Lenovo Thinkpad T440s")
- and the content of ``/sys/class/dmi/id/modalias``.
When you file a bug, please attach the following information:
-- a virtual description of your input device, see :ref:`evemu`. This is the
- most important piece of information, do not forget it!
+- a virtual description of your input device, see :ref:`libinput-record`.
+ This is the most important piece of information, do not forget it!
- the vendor model number of the device (e.g. "Logitech M325")
- the output from udevadm info, see :ref:`udev_info`.
When you file a bug, please attach the following information:
-- a virtual description of your input device, see :ref:`evemu`. This is the
- most important piece of information, do not forget it!
+- a virtual description of your input device, see :ref:`libinput-record`.
+ This is the most important piece of information, do not forget it!
.. _reporting_bugs_trackpoint:
When you file a bug, please attach the following information:
-- a virtual description of your input device, see :ref:`evemu`. This is the
- most important piece of information, do not forget it!
+- a virtual description of your input device, see :ref:`libinput-record`.
+ This is the most important piece of information, do not forget it!
- the vendor model number of the device (e.g. "Logitech M325")
- the output from udevadm info, see :ref:`udev_info`.
- the output of ``libinput measure trackpoint-range``
When you file a bug, please attach the following information:
-- a virtual description of your input device, see :ref:`evemu`. This is the
- most important piece of information, do not forget it!
+- a virtual description of your input device, see :ref:`libinput-record`.
+ This is the most important piece of information, do not forget it!
- the vendor model number of the device (e.g. "Sony Plastation3 controller")
.. _udev_info:
Recording devices with evemu
------------------------------------------------------------------------------
-.. note:: Where available, the :ref:`libinput-record` tools should be used instead
- of evemu
+.. warning:: Where available, the :ref:`libinput-record` tools should be used instead
+ of evemu
`evemu-record <https://www.freedesktop.org/wiki/Evemu/>`_ records the
device capabilities together with the event stream from the kernel. On our
If the bug is triggered by replaying on your device, attach the recording to
the bug report.
-.. note:: libinput does not affect the evemu recording. libinput and evemu talk
- directly to the kernel's device nodes. An evemu recording is not
- influenced by the libinput version or whether a libinput context is
- currently active.
+libinput does not affect the evemu recording. libinput and evemu talk
+directly to the kernel's device nodes. An evemu recording is not
+influenced by the libinput version or whether a libinput context is
+currently active.
.. graphviz:: evemu.gv
libinput record and libinput replay
------------------------------------------------------------------------------
+.. note:: For libinput versions 1.10 and older, use :ref:`evemu`.
+
The ``libinput record`` command records the **kernel** events from a specific
device node. The recorded sequence can be replayed with the ``libinput
replay`` command. This pair of tools is crucial to capturing bugs and
reproducing them on a developer's machine.
-.. note:: These tools are shipped with libinput, but the recorded events
- are **kernel events** and independent of the libinput context. libinput
- does not need to be running, it does not matter whether a user is
- running X.Org or Wayland or even what version of libinput is currently
- running.
+.. graphviz:: libinput-record.gv
+ :align: center
+
+The recorded events are **kernel events** and independent of the
+libinput context. libinput does not need to be running, it does
+not matter whether a user is running X.Org or Wayland or even what
+version of libinput is currently running.
The use of the tools is straightforward, just run without arguments, piping
the output into a file: ::
events to the file it is redirected to. More arguments are available, see
the **libinput-record(1)** man page.
+.. note:: When reproducing a bug that crashes libinput, run inside ``screen`` or
+ ``tmux``.
+
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
alphanumeric key shows up as letter "a".
-.. note:: When reproducing a bug that crashes libinput, run inside ``screen`` or
- ``tmux``.
+.. warning:: The longer the recording, the harder it is to identify the event
+ sequence triggering the bug. Please keep the event sequence as
+ short as possible.
The recording can be replayed with the ``libinput replay`` command: ::
What libinput is
------------------------------------------------------------------------------
-libinput is an input stack to be used by those applications that need full
-input device processing by commonly used input devices. That includes mice,
-keyboards, touchpads, touchscreens and graphics tablets. libinput handles
-device-specific quirks and provides an easy-to-use interface to receive
+libinput is an input stack for applications that need full input device
+processing by commonly used input devices. That includes mice, keyboards,
+touchpads, touchscreens and graphics tablets. libinput handles
+device-specific quirks and provides an easy-to-use API to receive
events from devices.
-libinput is designed to handle all input devices available on a system. It
-is possible to limit the devices that employ libinput. For example, the use
-of xf86-input-libinput depends on xorg.conf snippets for specific
-devices. But libinput works best if it handles all input devices as this
-allows for cross-device monitoring of events and smarter handling of
-features that affect multiple devices.
-
-libinput restricts device-specific features to applicable devices only.
-Devices with specific hardware properties may expose extra features, but
-these features are not made available on other devices, even where it may be
-possible to do so. One example for this are the top software buttons on the
-touchpad in the Lenovo T440 and similar devices. While there may be
-use-cases for providing top software buttons on other devices, libinput does
-not do so.
+libinput is designed to handle all input devices available on a system but
+it is possible to limit which devices libinput has access to.
+For example, the use of xf86-input-libinput depends on xorg.conf snippets
+for specific devices. But libinput works best if it handles all input
+devices as this allows for smarter handling of features that affect multiple
+devices.
+
+libinput restricts device-specific features to those devices that require
+those features. One example for this are the top software buttons on the
+touchpad in the Lenovo T440. While there may be use-cases for providing top
+software buttons on other devices, libinput does not do so.
.. _what_libinput_is_not:
libinput is **not** a box of legos. It does not provide the pieces to
assemble a selection of features. Many features can be disabled through
-configuration options, but some features are hardcoded or hardcoded on some
-devices. This usually matches the intended use of the device. There are
-plenty of use-cases to provide out-of-the-ordinary features, but libinput is
-not the place to support these.
+configuration options, but some features are hardcoded and/or only available
+on some devices. There are plenty of use-cases to provide niche features,
+but libinput is not the place to support these.
libinput is **not** a showcase for features. There are a lot of potential
features that could be provided on input devices. But unless they have
projects / platform / upstream / libinput.git / commitdiff