mirror of
https://gitlab.freedesktop.org/libinput/libinput.git
synced 2026-02-04 11:40:30 +01:00
doc/user: expand the contributing document and make it top-level
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer
parent
ce8b256f91
commit
2d77260ba5
3 changed files with 118 additions and 6 deletions
|
|
@ -5,18 +5,130 @@
|
|||
Contributing to libinput
|
||||
==============================================================================
|
||||
|
||||
Contributions to libinput are always welcome. Please see the steps below for
|
||||
details on how to create merge requests, correct git formatting and other
|
||||
topics:
|
||||
|
||||
So you want to contribute to libinput? Great! Here's a bunch of information
|
||||
that should get you started.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
Questions regarding this process can be asked on ``#wayland-devel`` on
|
||||
freenode or on the `wayland-devel@lists.freedesktop.org
|
||||
------------------------------------------------------------------------------
|
||||
Contact
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
Questions can be asked on ``#wayland-devel`` on freenode or on the
|
||||
`wayland-devel@lists.freedesktop.org
|
||||
<https://lists.freedesktop.org/mailman/listinfo/wayland-devel>`_ mailing
|
||||
list.
|
||||
|
||||
For IRC, ping user ``whot`` (Peter Hutterer, the libinput maintainer) though
|
||||
note that he lives on UTC+10 and thus the rest of the world is out of sync
|
||||
by default ;)
|
||||
|
||||
For anything that appears to be device specific and/or related to a new
|
||||
feature, just file `an issue in our issue tracker
|
||||
<https://gitlab.freedesktop.org/libinput/libinput/issues>`_. It's usually the
|
||||
most efficient way to get answers.
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
What to hack on?
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
If you don't already know what you want to improve or fix with libinput,
|
||||
then a good way of finding something is to search for the ``help needed``
|
||||
tag in our `issue tracker <https://gitlab.freedesktop.org/libinput/libinput/issues?label_name%5B%5D=help+needed>`_.
|
||||
These are issues that have been triaged to some degree and deemed to be a
|
||||
possible future feature to libinput.
|
||||
|
||||
.. note:: Some of these issue may require specific hardware to reproduce.
|
||||
|
||||
Another good place to help out with is the documentation. For anything you
|
||||
find in these pages that isn't clear enough please feel free to reword it
|
||||
and add what is missing.
|
||||
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
Getting the code
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
The :ref:`building_libinput` have all the details but the short solution
|
||||
will be:
|
||||
|
||||
::
|
||||
|
||||
$> git clone https://gitlab.freedesktop.org/libinput/libinput
|
||||
$> cd libinput
|
||||
$> meson --prefix=/usr builddir/
|
||||
$> ninja -C builddir/
|
||||
$> sudo ninja -C builddir/ install
|
||||
|
||||
You can omit the last step if you only want to test locally.
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
Hacking on things
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
libinput has a roughly three-parts architecture:
|
||||
|
||||
- the front-end code which handles the ``libinput_some_function()`` API calls in ``libinput.c``
|
||||
- the generic evdev interface handling which maps those API calls to the
|
||||
backend calls (``evdev.c``).
|
||||
- there are device-specific backends which do most of the actual work -
|
||||
``evdev-mt-touchpad.c`` is the one for touchpads for example.
|
||||
|
||||
In general, things that only affect the internal workings of a device only
|
||||
get implemented in the device-specific backend. You only need to touch the
|
||||
API when you are adding configuration options. For more details, please read
|
||||
the :ref:`architecture` document. There's also a `blog post describing the
|
||||
building blocks
|
||||
<https://who-t.blogspot.com/2019/03/libinputs-internal-building-blocks.html>`_
|
||||
that may help to understand how it all fits together.
|
||||
|
||||
Documentation is in ``/doc/api`` for the doxygen-generated API documentation.
|
||||
These are extracted from the libinput source code directly. The
|
||||
documentation you're reading right now is in ``/doc/user`` and generated with
|
||||
sphinx. Simply running ``ninja -C builddir`` will rebuild it and the final
|
||||
product ends up in ``builddir/Documentation``.
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
Testing things
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
libinput provides a bunch of :ref:`tools` to debug any changes - without
|
||||
having to install libinput.
|
||||
|
||||
The two most useful ones are :ref:`libinput debug-events
|
||||
<libinput-debug-events>` and :ref:`libinput debug-gui <libinput-debug-gui>`.
|
||||
Both tools can be run from the build directory directly and are great for
|
||||
quick test iterations::
|
||||
|
||||
$> sudo ./builddir/libinput-debug-events --verbose
|
||||
$> sudo ./builddir/libinput-debug-gui --verbose
|
||||
|
||||
The former provides purely textual output and is useful for verifying event
|
||||
streams from buttons, etc. The latter is particularly useful when you are
|
||||
trying to debug pointer movement or placement. ``libinput debug-gui`` will
|
||||
also visualize the raw data from the device so you can compare pointer
|
||||
behavior with what comes from the kernel.
|
||||
|
||||
These tools create a new libinput context and will not affect your session's
|
||||
behavior. Only once you've installed libinput and restarted your session
|
||||
will your changes affect the X server/Wayland compositor.
|
||||
|
||||
Once everything seems to be correct, it's time to run the
|
||||
:ref:`test-suite`::
|
||||
|
||||
$> sudo ./builddir/libinput-test-suite
|
||||
|
||||
This test suite can take test names etc. as arguments, have a look at
|
||||
:ref:`test-suite` for more info. There are a bunch of other tests that are
|
||||
run by the CI on merge requests, you can run those locally with ::
|
||||
|
||||
$> sudo ninja -C builddir check
|
||||
|
||||
So it always pays to run that before submitting. This will also run the code
|
||||
through valgrind and pick up any memory leaks.
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
Submitting Code
|
||||
------------------------------------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -46,7 +46,6 @@ Hacking on libinput
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
contributing.rst
|
||||
architecture
|
||||
test-suite.rst
|
||||
pointer-acceleration.rst
|
||||
|
|
|
|||
|
|
@ -10,6 +10,7 @@
|
|||
faqs
|
||||
reporting-bugs
|
||||
troubleshooting
|
||||
contributing
|
||||
development
|
||||
API documentation <@HTTP_DOC_LINK@/api/>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue